Component reference
Toolbar
An editor toolbar with formatting and alignment commands.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import {
Toolbar,
ToolbarGroup,
ToolbarButton,
ToolbarSeparator,
ToolbarToggleGroup,
ToolbarToggleItem,
Badge,
Button
} from "@pimolu/react";
import { useState } from "react";
type Alignment = "left" | "center" | "right";
function AlignLeftIcon() {
return (
<svg
viewBox="0 0 20 20"
width="15"
height="15"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
aria-hidden="true"
>
<path d="M3 5h14M3 9h8M3 13h14M3 17h6" />
</svg>
);
}
function AlignCenterIcon() {
return (
<svg
viewBox="0 0 20 20"
width="15"
height="15"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
aria-hidden="true"
>
<path d="M3 5h14M6 9h8M3 13h14M7 17h6" />
</svg>
);
}
function AlignRightIcon() {
return (
<svg
viewBox="0 0 20 20"
width="15"
height="15"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
aria-hidden="true"
>
<path d="M3 5h14M9 9h8M3 13h14M11 17h6" />
</svg>
);
}
function TextPreview({ formats, alignment, }: {
formats: string[];
alignment: Alignment;
}) {
return (
<div
className="max-w-prose leading-relaxed"
style={{
minHeight: 96,
padding: 16,
border: "1px solid var(--pimolu-border)",
borderRadius: "var(--pimolu-radius-md)",
background: "var(--pimolu-surface)",
fontWeight: formats.includes("bold") ? 700 : 400,
fontStyle: formats.includes("italic")
? "italic"
: "normal",
textDecoration: formats.includes("underline")
? "underline"
: "none",
textAlign: alignment,
}}
>
The release is ready. Toggle the controls above to apply
formatting to this paragraph.
</div>
);
}
function EditorToolbar({
formats,
alignment,
onFormatsChange,
onAlignmentChange,
onAction,
}: {
formats: string[];
alignment: Alignment;
onFormatsChange: (value: string[]) => void;
onAlignmentChange: (value: string) => void;
onAction: (action: string) => void;
}) {
return (
<Toolbar aria-label="Editor toolbar">
<ToolbarGroup aria-label="History">
<ToolbarButton aria-label="Undo" title="Undo" onClick={() => onAction("Undo")}>
<span aria-hidden="true">↶</span>
</ToolbarButton>
<ToolbarButton aria-label="Redo" title="Redo" onClick={() => onAction("Redo")}>
<span aria-hidden="true">↷</span>
</ToolbarButton>
</ToolbarGroup>
<ToolbarSeparator />
<ToolbarToggleGroup
type="multiple"
aria-label="Text formatting"
value={formats}
onValueChange={onFormatsChange}
>
<ToolbarToggleItem value="bold" aria-label="Bold">
<strong aria-hidden="true">B</strong>
</ToolbarToggleItem>
<ToolbarToggleItem value="italic" aria-label="Italic">
<em aria-hidden="true">I</em>
</ToolbarToggleItem>
<ToolbarToggleItem value="underline" aria-label="Underline">
<span aria-hidden="true" style={{ textDecoration: "underline" }}>U</span>
</ToolbarToggleItem>
</ToolbarToggleGroup>
<ToolbarSeparator />
<ToolbarToggleGroup
type="single"
aria-label="Alignment"
value={alignment}
onValueChange={onAlignmentChange}
>
<ToolbarToggleItem value="left" aria-label="Align left">
<AlignLeftIcon />
</ToolbarToggleItem>
<ToolbarToggleItem value="center" aria-label="Align center">
<AlignCenterIcon />
</ToolbarToggleItem>
<ToolbarToggleItem value="right" aria-label="Align right">
<AlignRightIcon />
</ToolbarToggleItem>
</ToolbarToggleGroup>
<ToolbarSeparator />
<ToolbarButton aria-label="Insert link" onClick={() => onAction("Insert link")}>Link</ToolbarButton>
<ToolbarButton disabled>Share</ToolbarButton>
</Toolbar>
);
}
export function DemoExample() {
const [formats, setFormats] = useState<string[]>([
"bold",
]);
const [alignment, setAlignment] = useState<Alignment>("left");
const [lastAction, setLastAction] = useState("Nothing selected yet");
return (
<div className="grid gap-5 min-w-0">
<div
className="flex flex-wrap items-center gap-3 min-w-0 justify-between"
style={{
flexWrap: "wrap"
}}
>
<EditorToolbar
formats={formats}
alignment={alignment}
onFormatsChange={setFormats}
onAlignmentChange={(value) => setAlignment(value as Alignment)}
onAction={setLastAction}
/>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Badge variant="primary">
{
formats.length > 0
? formats.join(" + ")
: "no formatting"
}
</Badge>
<Badge variant="neutral">
{alignment}
</Badge>
</div>
</div>
<TextPreview formats={formats} alignment={alignment} />
<div className="flex flex-wrap items-center gap-3 min-w-0 justify-between">
<span className="text-sm text-muted leading-relaxed">
Last action: {lastAction}
</span>
<Button
size="sm"
appearance="ghost"
onClick={() => {
setFormats([]);
setAlignment("left");
setLastAction("Formatting cleared");
}}
>
Reset formatting
</Button>
</div>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
History actions
A toolbar with disabled history actions and an observable save command.
Vertical rail
With orientation="vertical", the arrow axis turns and separators become horizontal. The toolbar still has a single tab stop.
Links, disabled root and navigation
ToolbarLink keeps link semantics. A disabled toolbar disables every control at once, including links.
Usage
Keep related commands together and use groups or separators to clarify their relationship.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluToolbarProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | — | Public Pimolu prop; see the source declaration for details. |
orientation | PimoluToolbarOrientation | undefined | "horizontal" | Layout and arrow-key axis. Defaults to "horizontal". |
label | string | undefined | "Toolbar" | Accessible name of the toolbar. Defaults to "Toolbar". |
disabled | boolean | undefined | false | Disable every control in the toolbar. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
childrenRequiredReactNodeNo default extracted.
Public Pimolu prop; see the source declaration for details.
orientationPimoluToolbarOrientation | undefinedDefault: "horizontal"
Layout and arrow-key axis. Defaults to "horizontal".
labelstring | undefinedDefault: "Toolbar"
Accessible name of the toolbar. Defaults to "Toolbar".
disabledboolean | undefinedDefault: false
Disable every control in the toolbar.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluToolbarGroupProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | — | Public Pimolu prop; see the source declaration for details. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
childrenRequiredReactNodeNo default extracted.
Public Pimolu prop; see the source declaration for details.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluToolbarButtonProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Public Pimolu prop; see the source declaration for details. |
disabled | boolean | undefined | false | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
type | "submit" | "reset" | "button" | undefined | — | Standard React/HTML attribute. |
value | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onChange | ChangeEventHandler<HTMLButtonElement, Element> | undefined | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLButtonElement> | undefined | — | Standard React/HTML attribute. |
childrenReactNodeNo default extracted.
Public Pimolu prop; see the source declaration for details.
disabledboolean | undefinedDefault: false
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
type"submit" | "reset" | "button" | undefinedNo default extracted.
Standard React/HTML attribute.
valuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onChangeChangeEventHandler<HTMLButtonElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLButtonElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluToolbarLinkProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
current | boolean | undefined | false | Mark the link as the current page. |
type | string | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onChange | ChangeEventHandler<HTMLAnchorElement, Element> | undefined | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLAnchorElement> | undefined | — | Standard React/HTML attribute. |
currentboolean | undefinedDefault: false
Mark the link as the current page.
typestring | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onChangeChangeEventHandler<HTMLAnchorElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLAnchorElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluToolbarSeparatorProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
aria-label | string | undefined | — | Kept for a consumer that wants a different accessible label. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
aria-labelstring | undefinedNo default extracted.
Kept for a consumer that wants a different accessible label.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluToolbarToggleGroupProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | — | Public Pimolu prop; see the source declaration for details. |
disabled | boolean | undefined | false | Disable every toggle in this group. |
className | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-label | string | undefined | — | Accessible name of the group. |
aria-labelledby | string | undefined | — | Id of the element that names the group. |
type | "single" | "multiple" | undefined | — | One selected value at a time. Any number of selected values. |
value | string | string[] | undefined | — | Public Pimolu prop; see the source declaration for details. |
defaultValue | string | string[] | undefined | — | Public Pimolu prop; see the source declaration for details. |
onValueChange | ((value: string) => void) | ((value: string[]) => void) | undefined | — | Public Pimolu prop; see the source declaration for details. |
childrenRequiredReactNodeNo default extracted.
Public Pimolu prop; see the source declaration for details.
disabledboolean | undefinedDefault: false
Disable every toggle in this group.
classNamestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-labelstring | undefinedNo default extracted.
Accessible name of the group.
aria-labelledbystring | undefinedNo default extracted.
Id of the element that names the group.
type"single" | "multiple" | undefinedNo default extracted.
One selected value at a time. Any number of selected values.
valuestring | string[] | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
defaultValuestring | string[] | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onValueChange((value: string) => void) | ((value: string[]) => void) | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
PimoluToolbarToggleItemProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
valueRequired | string | — | Value toggled by this item. |
childrenRequired | ReactNode | — | Public Pimolu prop; see the source declaration for details. |
onChange | ChangeEventHandler<HTMLButtonElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLButtonElement> | undefined | — | Standard React/HTML attribute. |
disabled | boolean | undefined | false | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
valueRequiredstringNo default extracted.
Value toggled by this item.
childrenRequiredReactNodeNo default extracted.
Public Pimolu prop; see the source declaration for details.
onChangeChangeEventHandler<HTMLButtonElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLButtonElement> | undefinedNo default extracted.
Standard React/HTML attribute.
disabledboolean | undefinedDefault: false
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Check roving focus, disabled-item skipping and the names of every icon button.