ki-toolbar
@kimen/elements/ki-toolbar- Source
- Agent reference
Use a toolbar for a few related page actions. A floating toolbar is a pill
that you place in your layout or over your content. Set
orientation="vertical" when the actions run down the side of the content.
<ki-toolbar label="Formatting"><ki-button variant="ghost" size="sm">Bold</ki-button><ki-divider orientation="vertical"></ki-divider><ki-button variant="ghost" size="sm">Insert link</ki-button></ki-toolbar>For a separate primary action, put a companion FAB in slot="fab". It
appears after the floating pill in reading order and has its own Tab stop.
A docked toolbar uses the full bottom edge and includes the device’s bottom
safe area. Reserve that edge for its horizontal action group on compact
screens and leave enough space below content for the bar. Use MobileNav
on screens that need navigation at that edge.
Supply a toolbar label, slot actions directly, and give every icon-only action a name. Tab enters on the most recently focused action. Arrow keys follow the layout and wrap at the ends. Home and End reach the first and last available action. Buttons own their activation and toggle state.
Use hide-on-scroll to free space while scrolling down the page. Scrolling
up or tabbing to an action brings the surface back. The toolbar stays visible
while an action or the companion FAB has focus.
API reference
When to use: group a small set of related page actions, such as text formatting or the commands on a compact message screen.
When not to use: for site navigation, mutually exclusive choices, or a docked bar on a screen already using MobileNav.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
hide-on-scroll | hideOnScroll | boolean | false | Hides on downward page scroll and reveals on upward scroll or when an action receives focus. Use for secondary actions where content needs room. |
label | label | string | – | Accessible name for the group, such as "Formatting". Supply it in the page's language. |
orientation | orientation | "horizontal" | "vertical" | 'horizontal' | Layout and keyboard axis. Set vertical for a floating column. Docked is always horizontal. |
tone | tone | "standard" | "vibrant" | 'standard' | Surface palette. Use vibrant to emphasize the toolbar with an accent tint. |
variant | variant | "docked" | "floating" | 'floating' | Floating leaves placement to the page. Docked fixes the surface to the viewport's bottom edge. Reserve space below the content when docking. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-button, ki-icon-button (including toggles), native button and ki-divider children. Give every icon-only action an accessible name. |
fab | A companion ki-fab for the floating variant. It follows the toolbar and has its own Tab stop. |
CSS parts
| Part | Description |
|---|---|
toolbar | The named surface containing the grouped actions. |
CSS custom properties
The public styling contract of ki-toolbar: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-toolbar-backdrop-filter | Complete backdrop filter behind the surface. |
--ki-toolbar-bg | Background of the standard toolbar. |
--ki-toolbar-bg-image | Optional image above the solid surface color. |
--ki-toolbar-docked-padding-inline | Inline insets for docked actions. |
--ki-toolbar-docked-radius | Corner radius of the docked toolbar. |
--ki-toolbar-fab-gap | Gap between a floating pill and its companion FAB. |
--ki-toolbar-fg | Foreground of the standard toolbar. |
--ki-toolbar-gap | Gap between toolbar actions. |
--ki-toolbar-height | Minimum height of the docked toolbar before its safe area. |
--ki-toolbar-padding | Toolbar surface padding. |
--ki-toolbar-radius | Radius of the floating pill. |
--ki-toolbar-scroll-duration | Duration of the scroll visibility transition. |
--ki-toolbar-scroll-easing | Easing of the scroll visibility transition. |
--ki-toolbar-shadow | Resting elevation of the floating pill. |
--ki-toolbar-vibrant-bg | Accent background of the vibrant toolbar. |
--ki-toolbar-vibrant-fg | Foreground on the vibrant toolbar. |
--ki-typography-family-body | semantic font family for typography family body. |