Theme
Version
GitHub PyPI Discord
On this page

Button Group

Use CButtonGroup when several Buttons perform closely related actions. It owns grouping and layout, not selection.

Button Group at a glance

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

Give every group a concise accessible label. Buttons remain ordinary native actions.

Group related 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.

Compare attached and spaced groups
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.

Choose Button Group layout
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.

Compose mixed Button actions
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.

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

InputTypeDefaultEffect
labelstrrequiredSupplies the accessible name for the related action group.
orientation"horizontal" | "vertical" (CButtonGroupOrientation)"horizontal"Selects the action layout axis.
attachedboolTrueJoins direct CButton children with shared edge geometry.
growboolFalseDistributes direct CButton children evenly across the available inline size.
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 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

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

VariableTypePurposeDefault
--cui-button-group-gaplengthGap between nonattached actions.0.5rem
--cui-button-group-radiuslengthOuter corner radius of attached direct Buttons.0.55rem
--cui-button-group-border-widthlengthAdjacent 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

AttributeElementTypeMeaning
data-orientationRoot"horizontal" | "vertical"Reflects the layout axis.
data-attachedRootpresent-or-absentPresent when direct Buttons use joined geometry.
data-growRootpresent-or-absentPresent 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

SelectorElementPurpose
[data-citry-ui-part="button-group"]RootStable group and attrs destination.
[data-citry-ui-part="button"]Direct CButton rootApplies joined geometry to direct Button children through the CButton public selector.

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]
CButtonGroupOrientationLiteral["horizontal", "vertical"]

CButtonGroupDefaultSlotData

Empty dataclass: {}.

Translation keys

-