Search docs

Toolbar

A row of controls, such as buttons and toggles, with one tab stop.

Toolbar follows the Toolbar WAI-ARIA design pattern.

import { $, component$, type PropsOf, Slot, sync$, useSignal, useStyles$ } from '@builder.io/qwik';
import { ToggleGroup } from '@leve-ui/toggle-group';
import { Toolbar } from '@leve-ui/toolbar';
import {
  LuAlignCenter,
  LuAlignLeft,
  LuAlignRight,
  LuBold,
  LuItalic,
  LuUnderline,
} from '@qwikest/icons/lucide';
import styles from './default.css?inline';

// Example of a router link component (such as Qwik City's <Link>) that spreads received props onto <a>
const ClientLink = component$<PropsOf<'a'>>(({ onClick$, ...props }) => {
  const visited = useSignal(false);
  const preventDefault$ = sync$((event: MouseEvent) => {
    event.preventDefault();
  });
  const handleClick$ = $(() => {
    visited.value = true;
  });

  return (
    <a
      {...props}
      data-visited={visited.value ? 'true' : undefined}
      onClick$={[preventDefault$, handleClick$, onClick$]}
    >
      <Slot />
    </a>
  );
});

export default component$(() => {
  useStyles$(styles);

  return (
    <Toolbar.Root aria-label="Formatting" class="toolbar-default">
      {/* Toggle Group items inside a Toolbar join its arrow-key navigation */}
      <ToggleGroup.Root type="multiple" aria-label="Text style" class="toolbar-default-group">
        <ToggleGroup.Item value="bold" aria-label="Bold" class="toolbar-default-item">
          <LuBold class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="italic" aria-label="Italic" class="toolbar-default-item">
          <LuItalic class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="underline" aria-label="Underline" class="toolbar-default-item">
          <LuUnderline class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
      </ToggleGroup.Root>
      <Toolbar.Separator class="toolbar-default-separator" />
      <ToggleGroup.Root
        defaultValue={['left']}
        aria-label="Text alignment"
        class="toolbar-default-group"
      >
        <ToggleGroup.Item value="left" aria-label="Align left" class="toolbar-default-item">
          <LuAlignLeft class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="center" aria-label="Align center" class="toolbar-default-item">
          <LuAlignCenter class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="right" aria-label="Align right" class="toolbar-default-item">
          <LuAlignRight class="toolbar-default-icon" aria-hidden="true" />
        </ToggleGroup.Item>
      </ToggleGroup.Root>
      <Toolbar.Separator class="toolbar-default-separator" />
      <Toolbar.Link as={ClientLink} href="/history" class="toolbar-default-link">
        Edited 5 minutes ago
      </Toolbar.Link>
      <Toolbar.Button class="toolbar-default-button">Share</Toolbar.Button>
    </Toolbar.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/toolbar

Anatomy#

import { Toolbar } from '@leve-ui/toolbar'; // or '@leve-ui/core'

<Toolbar.Root>
  <Toolbar.Button />
  <Toolbar.Separator />
  <Toolbar.Link />
</Toolbar.Root>
PartElementDescription
Toolbar.Root<div>The toolbar. Moves focus between its items.
Toolbar.Button<button>A button in the toolbar. Use as to render another element or component.
Toolbar.Link<a>A link in the toolbar. Use as to render another element or a router link component.
Toolbar.Separator<div>A line between groups of items.

A component passed to as on Toolbar.Button or Toolbar.Link must spread the props it receives onto a single element, including id, tabIndex, aria-*, data-*, and on*$ event handlers.

Toggle and Toggle Group items placed inside a Toolbar become toolbar items automatically: arrow keys move across all of them, and the Toggle Group stops handling arrow keys itself.

Examples#

Vertical#

orientation="vertical" stacks the items, so Up and Down arrows move focus. The separators become horizontal. Disabled items are skipped, and a Toggle inside the toolbar joins it.

API Reference#

Root#

PropDefaultType
orientation'horizontal''horizontal' | 'vertical'

The orientation of the toolbar, which decides the arrow keys that move focus.

looptrueboolean

Whether arrow keys wrap from the last item to the first and vice versa.

Also accepts all <div> attributes.

Data attributeValue
data-leve-toolbarAlways present
data-orientation"horizontal" | "vertical"

Button#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-toolbar-buttonAlways present
data-leve-toolbar-itemAlways present (also on Toggle and Toggle Group items inside a Toolbar)
data-disabledPresent when disabled
PropDefaultType
as'a'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <a>. A component must spread the props it receives onto one element.

Also accepts all <a> attributes.

Data attributeValue
data-leve-toolbar-linkAlways present
data-leve-toolbar-itemAlways present

Separator#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-toolbar-separatorAlways present
data-orientation"vertical" in a horizontal toolbar, "horizontal" in a vertical one

Accessibility#

Complies with the Toolbar WAI-ARIA design pattern.

  • Toolbar.Root renders role="toolbar" and aria-orientation. Name it with aria-label or aria-labelledby.
  • The toolbar has one tab stop: the first enabled item, then the item that was focused last. The other items have tabindex="-1".
  • Toolbar.Separator renders role="separator" with an aria-orientation perpendicular to the toolbar.
  • Disabled buttons use the native disabled attribute and are skipped by the arrow keys.
  • Give icon-only items an aria-label.

Keyboard Interactions#

KeyDescription
TabMoves focus into the toolbar (to the item focused last), or out of it.
ArrowRight / ArrowLeftIn a horizontal toolbar, moves focus to the next / previous item. Wraps around when loop is true.
ArrowDown / ArrowUpIn a vertical toolbar, moves focus to the next / previous item. Wraps around when loop is true.
Home / EndMoves focus to the first / last item.
Enter / SpaceActivates the focused item.