When to use the Toolbar

The Toolbar component is designed for canvas-style tool panels — the kind you find in drawing or diagram editors. It groups ToolbarButton elements into a pill-shaped bar with hover tooltips and active highlights. Use it when you need:

A tool selector with an "active tool" state
A set of action buttons that animate between tool modes
A toolbar that fans out sub-panels for grouped tools

For a standard page action menu (Create / Edit / Delete over a data table), use DataPage.MenuItems instead.

Component overview

Component	Purpose
`Toolbar`	Container — renders a pill-shaped bar of buttons
`ToolbarButton`	Icon or text button with tooltip and optional active state
`ToolbarSeparator`	Visual divider between button groups
`ToolbarSection`	Animated section that transitions between named contexts
`ToolbarContext`	Named set of buttons inside a `ToolbarSection`
`ToolbarFanOutItem`	Button that slides out a horizontal sub-panel on click

All components import from the @cratis/components/Toolbar subpath (never the root barrel — see components.md):

import { Toolbar, ToolbarButton, ToolbarSeparator, ToolbarSection, ToolbarContext, ToolbarFanOutItem } from '@cratis/components/Toolbar';

Step 1 — Basic vertical toolbar

Place ToolbarButton elements inside Toolbar. The default orientation is vertical.

import { Toolbar, ToolbarButton } from '@cratis/components/Toolbar';

export const DrawingToolbar = () => (
    <Toolbar>
        <ToolbarButton icon='pi pi-arrow-up-left' tooltip='Select' />
        <ToolbarButton icon='pi pi-pencil' tooltip='Draw' />
        <ToolbarButton icon='pi pi-stop' tooltip='Rectangle' />
    </Toolbar>
);

Step 2 — Active state (selected tool)

Use the active prop to highlight the currently selected tool. Drive it from state:

import { useState } from 'react';
import { Toolbar, ToolbarButton } from '@cratis/components/Toolbar';

export const DrawingToolbar = () => {
    const [activeTool, setActiveTool] = useState('select');

    return (
        <Toolbar>
            <ToolbarButton
                icon='pi pi-arrow-up-left'
                tooltip='Select'
                active={activeTool === 'select'}
                onClick={() => setActiveTool('select')}
            />
            <ToolbarButton
                icon='pi pi-pencil'
                tooltip='Draw'
                active={activeTool === 'draw'}
                onClick={() => setActiveTool('draw')}
            />
            <ToolbarButton
                icon='pi pi-stop'
                tooltip='Rectangle'
                active={activeTool === 'rect'}
                onClick={() => setActiveTool('rect')}
            />
        </Toolbar>
    );
};

Step 3 — Separators

ToolbarSeparator draws a thin divider line between groups. Pass the same orientation as the enclosing Toolbar:

<Toolbar>
    <ToolbarButton icon='pi pi-pencil' tooltip='Draw' />
    <ToolbarButton icon='pi pi-stop' tooltip='Rectangle' />
    <ToolbarSeparator />
    <ToolbarButton icon='pi pi-undo' tooltip='Undo' />
    <ToolbarButton icon='pi pi-refresh' tooltip='Redo' />
</Toolbar>

Step 4 — Horizontal toolbar with text buttons

Pass orientation='horizontal' for a horizontal layout. Use text for buttons that display a value (e.g. zoom percentage):

import { useState } from 'react';
import { Toolbar, ToolbarButton, ToolbarSeparator } from '@cratis/components/Toolbar';

export const ZoomToolbar = () => {
    const [zoom, setZoom] = useState(100);

    return (
        <Toolbar orientation='horizontal'>
            <ToolbarButton icon='pi pi-minus' tooltip='Zoom out' tooltipPosition='bottom' onClick={() => setZoom(z => z - 10)} />
            <ToolbarButton text={`${zoom}%`} tooltip='Reset zoom' tooltipPosition='bottom' onClick={() => setZoom(100)} />
            <ToolbarButton icon='pi pi-plus' tooltip='Zoom in' tooltipPosition='bottom' onClick={() => setZoom(z => z + 10)} />
            <ToolbarSeparator orientation='horizontal' />
            <ToolbarButton icon='pi pi-question-circle' tooltip='Help' tooltipPosition='bottom' />
        </Toolbar>
    );
};

For horizontal toolbars, set tooltipPosition='bottom' (or 'top') so tooltips do not overlap the toolbar.

Step 5 — Animated context switching

ToolbarSection + ToolbarContext allows the toolbar to show different sets of buttons depending on the active mode. When activeContext changes, the buttons fade out, the section morphs to the new size, and the new buttons fade in.

import { useState } from 'react';
import { Toolbar, ToolbarButton, ToolbarSection, ToolbarContext } from '@cratis/components/Toolbar';

export const ContextualToolbar = () => {
    const [mode, setMode] = useState<'drawing' | 'text'>('drawing');

    return (
        <Toolbar>
            <ToolbarButton icon='pi pi-arrow-up-left' tooltip='Select' />
            <ToolbarSection activeContext={mode}>
                <ToolbarContext name='drawing'>
                    <ToolbarButton icon='pi pi-pencil' tooltip='Draw' />
                    <ToolbarButton icon='pi pi-stop' tooltip='Rectangle' />
                    <ToolbarButton icon='pi pi-circle' tooltip='Circle' />
                </ToolbarContext>
                <ToolbarContext name='text'>
                    <ToolbarButton icon='pi pi-align-left' tooltip='Align Left' />
                    <ToolbarButton icon='pi pi-align-center' tooltip='Align Center' />
                    <ToolbarButton icon='pi pi-align-right' tooltip='Align Right' />
                </ToolbarContext>
            </ToolbarSection>
            <ToolbarButton icon='pi pi-undo' tooltip='Undo' />
        </Toolbar>
    );
};

Only the ToolbarSection transitions. Buttons outside the section are unaffected.

Step 6 — Fan-out sub-panel

ToolbarFanOutItem replaces a regular button with one that fans out a horizontal panel of additional tools. Clicking the button again or anywhere outside closes the panel.

import { Toolbar, ToolbarButton, ToolbarFanOutItem } from '@cratis/components/Toolbar';

export const ShapesToolbar = () => (
    <Toolbar>
        <ToolbarButton icon='pi pi-arrow-up-left' tooltip='Select' />
        <ToolbarFanOutItem icon='pi pi-th-large' tooltip='Shapes'>
            <ToolbarButton icon='pi pi-stop' tooltip='Rectangle' />
            <ToolbarButton icon='pi pi-circle' tooltip='Circle' />
            <ToolbarButton icon='pi pi-minus' tooltip='Line' />
        </ToolbarFanOutItem>
    </Toolbar>
);

When the toolbar is on the right side of the screen, fan out to the left:

<ToolbarFanOutItem icon='pi pi-th-large' tooltip='Shapes' fanOutDirection='left'>
    ...
</ToolbarFanOutItem>

Props reference

`Toolbar`

Prop	Type	Default	Description
`children`	`ReactNode`	—	`ToolbarButton`, `ToolbarSeparator`, `ToolbarSection`, or `ToolbarFanOutItem` elements
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout direction

`ToolbarButton`

Prop	Type	Default	Description
`icon`	`string`	—	PrimeIcons CSS class (e.g. `'pi pi-pencil'`)
`text`	`string`	—	Text shown inside the button (use for values like zoom %)
`tooltip`	`string`	required	Tooltip text on hover
`active`	`boolean`	`false`	Highlights the button as selected
`onClick`	`() => void`	—	Click handler
`tooltipPosition`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'right'`	Tooltip position

`ToolbarSeparator`

Prop	Type	Default	Description
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Match the enclosing `Toolbar` orientation

`ToolbarSection`

Prop	Type	Default	Description
`activeContext`	`string`	first context name	Name of the active `ToolbarContext`
`children`	`ToolbarContext[]`	—	`ToolbarContext` children
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Match the enclosing `Toolbar`

`ToolbarContext`

Prop	Type	Default	Description
`name`	`string`	required	Identifier matched by `ToolbarSection.activeContext`
`children`	`ReactNode`	—	`ToolbarButton` elements for this context

`ToolbarFanOutItem`

Prop	Type	Default	Description
`icon`	`string`	required	PrimeIcons CSS class for the trigger button
`tooltip`	`string`	required	Tooltip for the trigger button
`tooltipPosition`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'right'`	Tooltip position
`fanOutDirection`	`'right' \| 'left'`	`'right'`	Direction the sub-panel slides out
`children`	`ReactNode`	—	`ToolbarButton` elements inside the fan-out panel

Multiple toolbar groups

Render separate Toolbar instances to create distinct groups:

<div className='flex flex-column gap-2'>
    <Toolbar>
        <ToolbarButton icon='pi pi-arrow-up-left' tooltip='Select' />
        <ToolbarButton icon='pi pi-pencil' tooltip='Draw' />
    </Toolbar>
    <Toolbar>
        <ToolbarButton icon='pi pi-undo' tooltip='Undo' />
        <ToolbarButton icon='pi pi-refresh' tooltip='Redo' />
    </Toolbar>
</div>

Validation

After creating or modifying a Toolbar component, run:

yarn lint
npx tsc -b

Fix all errors before proceeding.

Cratis/AI

AI とは？

お気に入りのAIに質問する

ドキュメント