# Toolbar

Place the toolbar above or below the page, choose its actions, and let it collapse into a “More actions” menu on narrow screens.

## Basics

`toolbar={{ position: 'top' }}` moves the toolbar above the page; the default is below it.

**Demo: Toolbar above the page**

```tsx
import { PdfViewer } from '@kingtech/react-pdf-viewer';

export default function Demo() {
  return <PdfViewer source="/samples/letter-3pages.pdf" toolbar={{ position: 'top' }} />;
}
```

The toolbar groups its controls into zoom, page navigation and actions. It is a single tab stop: <kbd>Tab</kbd> enters it and <kbd>←</kbd> <kbd>→</kbd> <kbd>Home</kbd> <kbd>End</kbd> move between controls. `toolbar={false}` hides it.

### Choosing actions

`actions` lists the controls to show. `hiddenWhenCompact` lists those hidden below `compactBreakpoint` (960px by default) outside fullscreen; by default that is rotate and print.

**Demo: Navigation, zoom and download only**

```tsx
import { PdfViewer, type ToolbarConfig } from '@kingtech/react-pdf-viewer';

const toolbar: ToolbarConfig = {
  actions: [
    'previousPage',
    'pageIndicator',
    'nextPage',
    'zoomOut',
    'zoomLevel',
    'zoomIn',
    'download',
  ],
  hiddenWhenCompact: ['download'],
};

export default function Demo() {
  return <PdfViewer source="/samples/multipage.pdf" toolbar={toolbar} />;
}
```

The order of controls within each group is fixed, so every toolbar reads the same way. The available actions are listed in the [`ToolbarAction` reference](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/toolbar-action/).

### Responsive overflow

The toolbar is always a single row. When it does not fit its container, the actions (fullscreen, rotate, download, print) move into a **⋮ More actions** menu; on very narrow viewers the zoom controls follow. Page navigation always stays visible.

**Demo: Drag the width to watch the toolbar collapse**

```tsx
import { PdfViewer } from '@kingtech/react-pdf-viewer';
import { useState } from 'react';

export default function Demo() {
  const [width, setWidth] = useState(420);

  return (
    <>
      <p className="demo-controls">
        <label>
          Container width: {width}px{' '}
          <input
            type="range"
            min={320}
            max={720}
            step={10}
            value={width}
            onChange={(event) => setWidth(Number(event.target.value))}
          />
        </label>
      </p>
      <div style={{ width, maxWidth: '100%', margin: '0 auto' }}>
        <PdfViewer source="/samples/letter-3pages.pdf" pageInput zoomReset />
      </div>
    </>
  );
}
```

The menu follows the WAI-ARIA menu button pattern (<kbd>Enter</kbd> or <kbd>↓</kbd> opens it, arrows move, <kbd>Esc</kbd> closes it and returns focus) and opens away from the edge the toolbar sits on.

## Customization

Colors, radius, spacing, button and icon sizes, and the menu surface are CSS variables.

**Demo: A pill-shaped purple toolbar**

```tsx
import { PdfViewer } from '@kingtech/react-pdf-viewer';
import type { CSSProperties } from 'react';

const style = {
  '--rpv-toolbar-bg': '#4c1d95',
  '--rpv-toolbar-radius': '999px',
  '--rpv-toolbar-padding-x': '24px',
  '--rpv-button-hover-bg': 'rgba(255, 255, 255, 0.18)',
  '--rpv-menu-bg': '#faf5ff',
} as CSSProperties;

export default function Demo() {
  return <PdfViewer source="/samples/letter-3pages.pdf" style={style} />;
}
```

All toolbar variables (`--rpv-toolbar-*`, `--rpv-button-*`, `--rpv-menu-*`) are listed in the [CSS variables reference](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/css-variables/); see also the [customization guide](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/customization/).

## Advanced / escape hatch

To replace the toolbar with your own UI, or place parts of the default toolbar somewhere else, use [`renderToolbar`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/custom-toolbar/) with [`PdfToolbar`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-toolbar/).

## Limitations

- **Controls cannot be reordered within a group.** `actions` selects controls but keeps their order. Workaround: build your own toolbar with [`renderToolbar`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/custom-toolbar/).
- **The compact layout follows the window width, not the container.** `compactBreakpoint` compares with the viewport, while the overflow menu reacts to the container. Workaround: set `compactBreakpoint={0}` in narrow containers on wide screens and rely on the overflow menu.
- **No custom buttons in the default toolbar.** Workaround: render `PdfToolbar` next to your own buttons inside `renderToolbar`.

## API

- [ToolbarConfig](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/toolbar-config.md)
- [ToolbarAction](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/toolbar-action.md)

---

## ToolbarConfig reference

Toolbar customization: where the toolbar sits, which controls it shows and in which order, and which it hides on narrow screens.

### Used by

- [Toolbar](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/toolbar.md)

### Import

```ts
import type { ToolbarConfig } from '@kingtech/react-pdf-viewer';
```

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `position` | `'top' \| 'bottom'` | `'bottom'` | No | Toolbar placement (below the page by default). |
| `actions` | `readonly ToolbarAction[]` | `all actions` | No | Actions to show. Their order within each group is fixed. |
| `hiddenWhenCompact` | `readonly ToolbarAction[]` | `['rotate', 'print']` | No | Actions hidden in compact, non-fullscreen mode. |

### Source

[packages/react-pdf-viewer/src/types.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/types.ts#L136)


---

## ToolbarAction reference

Identifies a toolbar control, for choosing which controls the toolbar shows and in which order through `ToolbarConfig`.

### Used by

- [Toolbar](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/toolbar.md)

### Import

```ts
import type { ToolbarAction } from '@kingtech/react-pdf-viewer';
```

Signature: `type ToolbarAction = 'zoomOut' | 'zoomLevel' | 'zoomIn' | 'previousPage' | 'pageIndicator' | 'nextPage' | 'fullscreen' | 'rotate' | 'download' | 'print'`

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `zoomOut` | `'zoomOut'` | — | No | Zoom out button. Zoom group. |
| `zoomLevel` | `'zoomLevel'` | — | No | Zoom percentage; a reset button with `zoomReset`. Zoom group. |
| `zoomIn` | `'zoomIn'` | — | No | Zoom in button. Zoom group. |
| `previousPage` | `'previousPage'` | — | No | Previous page button. Page group. |
| `pageIndicator` | `'pageIndicator'` | — | No | Current page and total; an input with `pageInput`. Page group. |
| `nextPage` | `'nextPage'` | — | No | Next page button. Page group. |
| `fullscreen` | `'fullscreen'` | — | No | Enter / exit fullscreen. Actions group. |
| `rotate` | `'rotate'` | — | No | Rotate 90° clockwise. Actions group. |
| `download` | `'download'` | — | No | Save the loaded document. Actions group. |
| `print` | `'print'` | — | No | Print according to `printMode`. Actions group. |

### Source

[packages/react-pdf-viewer/src/types.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/types.ts#L44)