Theme
Version
GitHub PyPI Discord
On this page

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

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.

Group persistent commands
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.

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.

Compose Toolbar controls
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.

Choose Toolbar orientation
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.

Compare Toolbar variants and sizes
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.

Toolbar disabled controls
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.

Customize Toolbar
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(...).

InputTypeDefaultEffect
labelstrrequiredSupplies the accessible Toolbar name.
orientation"horizontal" | "vertical" (CToolbarOrientation)"horizontal"Selects layout and arrow-key axis.
loopboolTrueWraps 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)NoneAdds root classes.
stylestr | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
orientation"horizontal" | "vertical" (CToolbarOrientation)Uses the server value.Reactively changes layout ARIA orientation and arrow-key axis.
loopboolUses 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

SlotRequiredDataFallback
defaultyes{} (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.

VariableTypePurposeDefault
--cui-toolbar-gaplengthGap between Toolbar children.sm: 0.375rem; md: 0.5rem; lg: 0.625rem
--cui-toolbar-paddinglengthToolbar inner padding.sm: 0.25rem; md: 0.375rem; lg: 0.5rem
--cui-toolbar-min-heightlengthMinimum logical Toolbar height.sm: 2.25rem; md: 2.75rem; lg: 3.25rem
--cui-toolbar-radiuslengthToolbar corner radius.0.75rem
--cui-toolbar-backgroundcolorToolbar surface color.plain and outline: transparent; soft: a 7 percent CanvasText mix over Canvas
--cui-toolbar-foregroundcolorInherited Toolbar foreground.CanvasText
--cui-toolbar-border-colorcolorOutline Toolbar border.a 16 percent CanvasText mix
--cui-toolbar-focus-colorcolorFocus 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

AttributeElementTypeMeaning
roleRoottoolbarExposes one named Toolbar composite.
aria-labelRootstringSupplies the required accessible name.
aria-orientationRoothorizontal | verticalMirrors the effective navigation axis.
data-orientationRoothorizontal | verticalMirrors effective orientation.
data-loopRootpresent-or-absentPresent when arrow navigation wraps.
data-variantRootplain | soft | outlineMirrors effective variant.
data-sizeRootsm | md | lgMirrors effective size.
tabindexOwned Button or link0 | -1Exactly 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

SelectorElementPurpose
[data-citry-ui-part="toolbar"]Root divStable Toolbar root and attrs destination.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue]
CToolbarOrientationLiteral["horizontal", "vertical"]
CToolbarVariantLiteral["plain", "soft", "outline"]
CToolbarSizeLiteral["sm", "md", "lg"]

CToolbarDefaultSlotData

Empty dataclass: {}.

Translation keys

-