Button Group
Use CButtonGroup when several Buttons perform closely related actions. It owns grouping and layout, not selection.
Button Group at a glance
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ButtonGroupGlance(Component):
template = """
<c-CButtonGroup label="Telescope controls">
<c-CButton variant="outline">Previous</c-CButton>
<c-CButton variant="outline">Center</c-CButton>
<c-CButton variant="outline">Next</c-CButton>
</c-CButtonGroup>
"""
preview = ButtonGroupGlance()
preview # noqa: B018
Group related actions
Give every group a concise accessible label. Buttons remain ordinary native actions.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class RelatedActions(Component):
template = """
<c-CButtonGroup label="Map controls">
<c-CButton variant="outline">Zoom in</c-CButton>
<c-CButton variant="outline">Reset</c-CButton>
<c-CButton variant="outline">Zoom out</c-CButton>
</c-CButtonGroup>
"""
preview = RelatedActions()
preview # noqa: B018
<c-CButtonGroup label="Map controls">
<c-CButton variant="outline">Zoom in</c-CButton>
<c-CButton variant="outline">Zoom out</c-CButton>
</c-CButtonGroup>
Attach or space Buttons
Attached groups share outer geometry. Set attached=False for separate Buttons that still belong to one named action set.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class Attachment(Component):
template = """
<c-CStack gap="md">
<c-CButtonGroup label="Attached view controls">
<c-CButton variant="outline">Map</c-CButton>
<c-CButton variant="outline">Sky</c-CButton>
</c-CButtonGroup>
<c-CButtonGroup label="Spaced view controls" c-attached="False">
<c-CButton variant="outline">Map</c-CButton>
<c-CButton variant="outline">Sky</c-CButton>
</c-CButtonGroup>
</c-CStack>
"""
preview = Attachment()
preview # noqa: B018
Choose orientation and growth
Vertical groups describe stacked actions. grow=True gives direct Buttons equal width.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class Layout(Component):
template = """
<c-CStack gap="lg">
<c-CButtonGroup label="Time range" c-grow="True">
<c-CButton variant="outline">Night</c-CButton>
<c-CButton variant="outline">Week</c-CButton>
<c-CButton variant="outline">Month</c-CButton>
</c-CButtonGroup>
<c-CButtonGroup label="Export format" orientation="vertical">
<c-CButton variant="outline">Star chart</c-CButton>
<c-CButton variant="outline">Observation log</c-CButton>
</c-CButtonGroup>
</c-CStack>
"""
preview = Layout()
preview # noqa: B018
Compose mixed actions
Each Button keeps its own variant, intent, loading, disabled, and link behavior. Use CToggleGroup instead when the Buttons represent selected choices.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class Composition(Component):
template = """
<c-CButtonGroup label="Expedition actions">
<c-CButton intent="primary">Save route</c-CButton>
<c-CButton variant="outline" href="/preview">Preview</c-CButton>
<c-CButton variant="ghost" intent="danger">Discard</c-CButton>
</c-CButtonGroup>
"""
preview = Composition()
preview # noqa: B018
Customize Button Group
Public variables control spacing, outer radius, and border overlap.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class Customization(Component):
template = """
<c-CButtonGroup class_="orbit-group" label="Orbit controls">
<c-CButton variant="outline">Inner</c-CButton>
<c-CButton variant="outline">Stable</c-CButton>
<c-CButton variant="outline">Outer</c-CButton>
</c-CButtonGroup>
"""
css = """
:where(.orbit-group) {
--cui-button-group-radius: 999px;
--cui-button-group-border-width: 2px;
}
"""
preview = Customization()
preview # noqa: B018
Accessibility and behavior
The root is a named group. Tab order, activation, Form behavior, loading, and disabled state belong to each Button. Button Group adds no JavaScript or roving focus.
API reference
Inputs
CButtonGroup server inputs
Server inputs are passed in a template through <c-CButtonGroup ... /> or in Python through CButtonGroup(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Supplies the accessible name for the related action group. |
orientation | "horizontal" | "vertical" (CButtonGroupOrientation) | "horizontal" | Selects the action layout axis. |
attached | bool | True | Joins direct CButton children with shared edge geometry. |
grow | bool | False | Distributes direct CButton children evenly across the available inline size. |
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 attributes without replacing group semantics, naming, layout reflections, children, focus ownership, or Citry runtime fields. |
Slots
Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.
CButtonGroup slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CButtonGroupDefaultSlotData) | None. |
Events
-
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CButtonGroup CSS variables
Apply these variables to CButtonGroup or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-button-group-gap | length | Gap between nonattached actions. | 0.5rem |
--cui-button-group-radius | length | Outer corner radius of attached direct Buttons. | 0.55rem |
--cui-button-group-border-width | length | Adjacent border overlap for attached Buttons. | 1px |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CButtonGroup attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-orientation | Root | "horizontal" | "vertical" | Reflects the layout axis. |
data-attached | Root | present-or-absent | Present when direct Buttons use joined geometry. |
data-grow | Root | present-or-absent | Present when direct Buttons share the available width. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CButtonGroup selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="button-group"] | Root | Stable group and attrs destination. |
[data-citry-ui-part="button"] | Direct CButton root | Applies joined geometry to direct Button children through the CButton public selector. |
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] |
CButtonGroupOrientation | Literal["horizontal", "vertical"] |
CButtonGroupDefaultSlotData
Empty dataclass: {}.
Translation keys
-