Toolbar

Toolbar is a compound component for creating action bars anchored to any edge. It builds on Card for visual styling and provides structured slots for content organization.

Use Toolbar inside dialogs, popovers, panels, or any container where you need persistent controls.

Installation

npm install @kushagradhawan/kookie-ui

Usage

import { Card, Flex, Toolbar, IconButton } from '@kushagradhawan/kookie-ui';
 
export function MyToolbar() {
  return (
    <Card variant="classic" size="2">
      <Toolbar variant="soft" size="1">
        <Toolbar.Left>
          <IconButton variant="ghost" size="2" color="gray" highContrast>
            <ArrowLeftIcon />
          </IconButton>
        </Toolbar.Left>
        <Toolbar.Center>
          <Toolbar.Title>Settings</Toolbar.Title>
        </Toolbar.Center>
        <Toolbar.Right>
          <IconButton variant="ghost" size="2" color="gray" highContrast>
            <CloseIcon />
          </IconButton>
        </Toolbar.Right>
      </Toolbar>
      <Flex p="4" pt="var(--rt-toolbar-height)">
        {/* Content */}
      </Flex>
    </Card>
  );
}

Toolbar uses absolute positioning to span edge-to-edge. Use --rt-toolbar-height (or --rt-toolbar-width for vertical toolbars) to add padding to your content.

Anatomy

Toolbar is a compound component with the following parts:

<Toolbar>
  <Toolbar.Left>{/* Start section content */}</Toolbar.Left>
  <Toolbar.Center>
    <Toolbar.Title>{/* Title text */}</Toolbar.Title>
  </Toolbar.Center>
  <Toolbar.Right>{/* End section content */}</Toolbar.Right>
</Toolbar>

Props

Root Props

The root component manages positioning and inherits Card's visual styling.

Section Props

Toolbar.Left, Toolbar.Center, and Toolbar.Right extend Flex and accept all Flex props. They are placed on a CSS grid for true centering regardless of content width.

Plus all other Flex props (direction, wrap, p, m, etc.).

Title Props

Toolbar.Title renders a truncated heading and accepts all Heading props with toolbar-appropriate defaults.

Anchor

Use the anchor prop to position the toolbar at different edges.

Top

The default. Anchors to the top of the scroll container.

<Toolbar anchor="top">
  <Toolbar.Center>
    <Toolbar.Title>Top Toolbar</Toolbar.Title>
  </Toolbar.Center>
</Toolbar>

Bottom

Anchors to the bottom, useful for action bars.

<Toolbar anchor="bottom">
  <Toolbar.Right>
    <Button>Save</Button>
  </Toolbar.Right>
</Toolbar>

Left / Right

Vertical toolbars for sidebar-style controls.

<Toolbar anchor="left">
  <Toolbar.Left>
    <IconButton variant="ghost" size="2">
      <HomeIcon />
    </IconButton>
  </Toolbar.Left>
</Toolbar>

Positioning Modes

Toolbar has two positioning modes: inset (default) and floating. Both use position: absolute.

Inset (Default)

By default, Toolbar uses inset mode to go edge-to-edge inside Cards.

<Card size="2">
  <Toolbar variant="soft">
    <Toolbar.Title>Edge-to-edge</Toolbar.Title>
  </Toolbar>
  <Flex p="4" pt="var(--rt-toolbar-height)">{/* Content */}</Flex>
</Card>

When inset (default):

• No border radius
• Edge-to-edge layout
• Only the exposed edge shows a border

Floating

Use floating for a detached look with margin from edges.

<Toolbar floating variant="surface">
  <Toolbar.Center>
    <Toolbar.Title>Floating Toolbar</Toolbar.Title>
  </Toolbar.Center>
</Toolbar>

When floating:

• Full border radius from Card
• Margin from container edges (controlled by offset)
• Complete Card styling (all borders visible)

Offset

Control the margin when floating with the offset prop.

<Toolbar floating offset="4" variant="surface">
  <Toolbar.Title>More spacing</Toolbar.Title>
</Toolbar>

Variants

Toolbar inherits all Card variants. The default is ghost for minimal visual weight.

Soft

Muted background, great for dialog headers.

<Toolbar variant="soft">
  <Toolbar.Title>Soft</Toolbar.Title>
</Toolbar>

Surface

Subtle background with border. Good for floating toolbars.

<Toolbar variant="surface" floating>
  <Toolbar.Title>Surface</Toolbar.Title>
</Toolbar>

Ghost

No visible background or border. Use when the parent provides visual context.

<Toolbar variant="ghost">
  <Toolbar.Title>Ghost</Toolbar.Title>
</Toolbar>

Sizes

Controls padding inside the toolbar.

<Toolbar size="1">{/* Compact */}</Toolbar>
<Toolbar size="2">{/* Default */}</Toolbar>
<Toolbar size="3">{/* Comfortable */}</Toolbar>

Material

Use material="translucent" for backdrop blur over images or dynamic backgrounds.

<Toolbar material="translucent" variant="soft">
  <Toolbar.Title>Translucent</Toolbar.Title>
</Toolbar>

CSS Variables

Toolbar exposes dimension variables so you can add padding to prevent content overlap:

• --rt-toolbar-height for horizontal toolbars (anchor="top" or anchor="bottom")
• --rt-toolbar-width for vertical toolbars (anchor="left" or anchor="right")

The variables are set on the Toolbar's parent element, so the Toolbar and content must share a common container:

<Card size="2">
  <Toolbar anchor="top">
    <Toolbar.Title>Top Toolbar</Toolbar.Title>
  </Toolbar>
  <Flex p="4" pt="var(--rt-toolbar-height)">
    {/* Content */}
  </Flex>
</Card>

For bottom-anchored toolbars, use pb="var(--rt-toolbar-height)" on your content instead.

For image or video backgrounds where content should flow behind the toolbar, simply don't apply the padding.

Accessibility

• Use semantic elements and ARIA attributes as needed
• For dialog/popover context, pair with appropriate aria-labelledby on the container
• Toolbar.Title can provide the ID for accessible labeling

<Dialog.Content aria-labelledby="toolbar-title">
  <Toolbar>
    <Toolbar.Title id="toolbar-title">Settings</Toolbar.Title>
  </Toolbar>
</Dialog.Content>