Toolbar
Use CToolbar for three or more persistent editor, map, table, or contextual controls. Toolbar owns focus movement only: Buttons own actions, Toggles own pressed state, and Menu or Popover owns its surface.
Toolbar at a glance
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarAtAGlance(Component):
template = """
<c-CToolbar label="Document tools" variant="soft">
<c-CButton variant="ghost">Undo</c-CButton>
<c-CToggle>Bold</c-CToggle>
<c-CToggle>Italic</c-CToggle>
<c-CDivider orientation="vertical" decorative />
<a href="#toolbar-preview">Help</a>
</c-CToolbar>
"""
preview = ToolbarAtAGlance()
preview # noqa: B018
Group persistent commands
Give each Toolbar a concise label. One owned control participates in the page Tab order; Left and Right move among controls in a horizontal Toolbar.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarCommands(Component):
template = """
<c-CToolbar label="Text formatting" variant="outline">
<c-CButton>Undo</c-CButton>
<c-CButton>Redo</c-CButton>
<c-CToggle c-pressed="True">Bold</c-CToggle>
<c-CToggle>Italic</c-CToggle>
</c-CToolbar>
"""
preview = ToolbarCommands()
preview # noqa: B018
<c-CToolbar label="Text formatting">
<c-CButton>Undo</c-CButton>
<c-CToggle>Bold</c-CToggle>
<c-CToggle>Italic</c-CToggle>
</c-CToolbar>
Use CButtonGroup instead when related actions should remain separate page Tab stops. Use CToggleGroup when a group owns one shared selection value.
Compose groups, separators, links, and overlays
ButtonGroup and ToggleGroup may organize controls without becoming a second focus owner. Divider stays noninteractive. Menu and Popover activators remain Toolbar controls while their opened surfaces keep independent focus behavior.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarComposition(Component):
template = """
<c-CToolbar label="Map tools" variant="soft">
<c-CButtonGroup label="Zoom">
<c-CButton variant="outline">Zoom in</c-CButton>
<c-CButton variant="outline">Zoom out</c-CButton>
</c-CButtonGroup>
<c-CDivider orientation="vertical" decorative />
<c-CToggleGroup label="Map layer" value="terrain">
<c-CToggle value="terrain">Terrain</c-CToggle>
<c-CToggle value="satellite">Satellite</c-CToggle>
</c-CToggleGroup>
<c-CPopover>
<c-fill name="activator" data="{ activator_attrs }">
<c-CButton c-attrs="activator_attrs">Details</c-CButton>
</c-fill>
<c-fill name="title">Map details</c-fill>
<c-fill name="default"><p>Projection and data source information.</p></c-fill>
</c-CPopover>
</c-CToolbar>
"""
preview = ToolbarComposition()
preview # noqa: B018
Choose orientation and boundaries
Vertical Toolbars use Up and Down. Home and End reach the first and last available control. Set loop=False when arrow movement should stop at an edge. Horizontal direction follows LTR or RTL.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarOrientation(Component):
template = """
<div style="display:grid; grid-template-columns:1fr auto; gap:1rem; align-items:start">
<c-CToolbar label="Horizontal tools" c-loop="False">
<c-CButton>Previous</c-CButton>
<c-CButton>Current</c-CButton>
<c-CButton>Next</c-CButton>
</c-CToolbar>
<c-CToolbar label="Vertical tools" orientation="vertical" variant="outline">
<c-CButton>Up</c-CButton>
<c-CButton>Center</c-CButton>
<c-CButton>Down</c-CButton>
</c-CToolbar>
</div>
"""
preview = ToolbarOrientation()
preview # noqa: B018
Compare variants and sizes
Plain adds no surface, soft adds a quiet background, and outline adds a boundary. Toolbar does not change child Button or Toggle variants.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarVariants(Component):
template = """
<c-CStack gap="md">
<c-CToolbar
c-for="variant, size in [('plain', 'sm'), ('soft', 'md'), ('outline', 'lg')]"
c-label="variant + ' ' + size + ' tools'"
c-variant="variant"
c-size="size"
>
<c-CButton>Cut</c-CButton>
<c-CButton>Copy</c-CButton>
<c-CButton>Paste</c-CButton>
</c-CToolbar>
</c-CStack>
"""
preview = ToolbarVariants()
preview # noqa: B018
Respect disabled ownership
Native disabled controls, aria-disabled="true", hidden or inert controls, disabled native fieldsets, and disabled CForm state are skipped. If the focused control becomes unavailable, focus moves to the nearest available Toolbar control only when focus had belonged to the Toolbar.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarDisabled(Component):
template = """
<fieldset disabled>
<legend>Unavailable editor</legend>
<c-CToolbar label="Unavailable tools" variant="outline">
<c-CButton>Cut</c-CButton>
<c-CButton>Copy</c-CButton>
<c-CButton>Paste</c-CButton>
</c-CToolbar>
</fieldset>
"""
preview = ToolbarDisabled()
preview # noqa: B018
Customize Toolbar
Public variables control the Toolbar surface and spacing. Child controls keep their own component variables and public parts.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ToolbarCustomization(Component):
template = """
<c-CToolbar
label="Forest tools"
variant="soft"
c-style="{
'--cui-toolbar-gap': '0.75rem',
'--cui-toolbar-radius': '1.25rem',
'--cui-toolbar-background': '#eef8ec',
'--cui-toolbar-border-color': '#497a43'
}"
>
<c-CButton variant="ghost">Canopy</c-CButton>
<c-CButton variant="ghost">Understory</c-CButton>
<c-CButton variant="ghost">Soil</c-CButton>
</c-CToolbar>
"""
preview = ToolbarCustomization()
preview # noqa: B018
Accessibility and content rules
Toolbar requires at least three owned Buttons or links after browser initialization. Do not place text inputs, selects, textareas, contenteditable regions, nested Toolbars, or authored tabindex inside it. Their keyboard or focus contracts conflict with Toolbar's roving focus. Icon-only controls still need their own accessible name.
Native Buttons remain responsible for type="button" when they must not submit a Form. Citry UI Button and Toggle already use form-safe Button roots.
API reference
Inputs
CToolbar server inputs
Server inputs are passed in a template through <c-CToolbar ... /> or in Python through CToolbar(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Supplies the accessible Toolbar name. |
orientation | "horizontal" | "vertical" (CToolbarOrientation) | "horizontal" | Selects layout and arrow-key axis. |
loop | bool | True | Wraps arrow movement at the first and last available controls. |
variant | "plain" | "soft" | "outline" (CToolbarVariant) | "plain" | Selects the Toolbar surface treatment. |
size | "sm" | "md" | "lg" (CToolbarSize) | "md" | Selects Toolbar gap padding and minimum height. |
class_ | str | Mapping[str, bool] | Sequence[CClassValue] | None (CClassValue) | None | Adds root classes. |
style | str | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] | None (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds copied trusted root attributes without replacing Toolbar semantics focus visibility reflections children or runtime markers. |
CToolbar client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CToolbar />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
orientation | "horizontal" | "vertical" (CToolbarOrientation) | Uses the server value. | Reactively changes layout ARIA orientation and arrow-key axis. |
loop | bool | Uses the server value. | Reactively enables or disables arrow-key wrapping. |
variant | "plain" | "soft" | "outline" (CToolbarVariant) | Uses the server value. | Reactively changes the surface treatment. |
size | "sm" | "md" | "lg" (CToolbarSize) | Uses the server value. | Reactively changes Toolbar geometry. |
Slots
Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.
CToolbar slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CToolbarDefaultSlotData) | None. Settled enhanced content requires at least three owned Buttons or links. |
Events
-
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CToolbar CSS variables
Apply these variables to CToolbar or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-toolbar-gap | length | Gap between Toolbar children. | sm: 0.375rem; md: 0.5rem; lg: 0.625rem |
--cui-toolbar-padding | length | Toolbar inner padding. | sm: 0.25rem; md: 0.375rem; lg: 0.5rem |
--cui-toolbar-min-height | length | Minimum logical Toolbar height. | sm: 2.25rem; md: 2.75rem; lg: 3.25rem |
--cui-toolbar-radius | length | Toolbar corner radius. | 0.75rem |
--cui-toolbar-background | color | Toolbar surface color. | plain and outline: transparent; soft: a 7 percent CanvasText mix over Canvas |
--cui-toolbar-foreground | color | Inherited Toolbar foreground. | CanvasText |
--cui-toolbar-border-color | color | Outline Toolbar border. | a 16 percent CanvasText mix |
--cui-toolbar-focus-color | color | Focus outline color for owned controls. | Highlight |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CToolbar attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
role | Root | toolbar | Exposes one named Toolbar composite. |
aria-label | Root | string | Supplies the required accessible name. |
aria-orientation | Root | horizontal | vertical | Mirrors the effective navigation axis. |
data-orientation | Root | horizontal | vertical | Mirrors effective orientation. |
data-loop | Root | present-or-absent | Present when arrow navigation wraps. |
data-variant | Root | plain | soft | outline | Mirrors effective variant. |
data-size | Root | sm | md | lg | Mirrors effective size. |
tabindex | Owned Button or link | 0 | -1 | Exactly one available control participates in the page Tab order. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CToolbar selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="toolbar"] | Root div | Stable Toolbar root and attrs destination. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] |
CToolbarOrientation | Literal["horizontal", "vertical"] |
CToolbarVariant | Literal["plain", "soft", "outline"] |
CToolbarSize | Literal["sm", "md", "lg"] |
CToolbarDefaultSlotData
Empty dataclass: {}.
Translation keys
-