Theme
Version
GitHub PyPI Discord
On this page

Toggle

Use CToggle for a Button whose pressed state persists. Use CToggleGroup for related exclusive or multiple choices.

Toggle at a glance

Toggle at a glance
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ToggleGlance(Component):
    template = """
      <c-CToggleGroup label="Star map layers" value="constellations" c-mandatory="True">
        <c-CToggle value="constellations">Constellations</c-CToggle>
        <c-CToggle value="planets">Planets</c-CToggle>
        <c-CToggle value="grid">Grid</c-CToggle>
      </c-CToggleGroup>
    """


preview = ToggleGlance()
preview  # noqa: B018

Choose Toggle, Switch, or Button Group

Toggle changes an active tool or view. Switch changes an immediate setting. Button Group groups related actions without selection.

Toggle one tool

Toggle one tool
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class StandaloneToggle(Component):
    template = """
      <c-CToggle c-pressed="True">Pin observation</c-CToggle>
    """


preview = StandaloneToggle()
preview  # noqa: B018

Select one or several values

Compare single and multiple Toggle Groups
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ToggleGroups(Component):
    template = """
      <c-CStack gap="lg">
        <c-CToggleGroup label="Chart scale" value="linear">
          <c-CToggle value="linear">Linear</c-CToggle>
          <c-CToggle value="log">Log</c-CToggle>
        </c-CToggleGroup>
        <c-CToggleGroup label="Visible layers" c-value="['stars', 'labels']" c-multiple="True">
          <c-CToggle value="stars">Stars</c-CToggle>
          <c-CToggle value="labels">Labels</c-CToggle>
          <c-CToggle value="grid">Grid</c-CToggle>
        </c-CToggleGroup>
      </c-CStack>
    """


preview = ToggleGroups()
preview  # noqa: B018

Keep one value selected

mandatory=True rejects only the user action that would clear the final value.

Keep one Toggle selected
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class MandatoryToggle(Component):
    template = """
      <c-CToggleGroup label="Coordinate system" value="equatorial" c-mandatory="True">
        <c-CToggle value="equatorial">Equatorial</c-CToggle>
        <c-CToggle value="galactic">Galactic</c-CToggle>
      </c-CToggleGroup>
    """


preview = MandatoryToggle()
preview  # noqa: B018

Control selection in the browser

Client inputs are passed with $c-props="{...}". onValueChange reports the next requested value.

Control Toggle selection
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ControlledToggle(Component):
    template = """
      <section x-data="{ view: 'sky' }">
        <p>Current view: <strong x-text="view"></strong></p>
        <c-CToggleGroup
          label="Observation view"
          value="sky"
          $c-props="{ value: view, onValueChange: (next) => view = next }"
        >
          <c-CToggle value="sky">Sky</c-CToggle>
          <c-CToggle value="spectrum">Spectrum</c-CToggle>
        </c-CToggleGroup>
      </section>
    """


preview = ControlledToggle()
preview  # noqa: B018

Choose presentation

Compare Toggle variants and sizes
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TogglePresentation(Component):
    template = """
      <c-CStack gap="md">
        <c-for each="variant in variants">
          <c-CToggleGroup c-label="variant + ' display'" value="one" c-variant="variant">
            <c-CToggle value="one">One</c-CToggle>
            <c-CToggle value="two">Two</c-CToggle>
          </c-CToggleGroup>
        </c-for>
      </c-CStack>
    """

    def template_data(self, kwargs, slots):  # noqa: ANN001, ANN201, ARG002
        return {"variants": ("soft", "outline", "plain")}


preview = TogglePresentation()
preview  # noqa: B018

Customize Toggle

Customize Toggle
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ToggleCustomization(Component):
    template = """
      <c-CToggleGroup class_="nebula-toggle" label="Nebula filter" value="oxygen">
        <c-CToggle value="oxygen">Oxygen</c-CToggle>
        <c-CToggle value="hydrogen">Hydrogen</c-CToggle>
      </c-CToggleGroup>
    """
    css = """
      :where(.nebula-toggle) {
        --cui-toggle-pressed-background: light-dark(#7c3aed, #a78bfa);
        --cui-toggle-pressed-foreground: white;
        --cui-toggle-radius: 999px;
      }
    """


preview = ToggleCustomization()
preview  # noqa: B018

Accessibility and behavior

Each Toggle is a native Button with aria-pressed. Space and Enter activate it. All enabled Toggles remain in ordinary Tab order; the family does not claim arrow keys or Form submission.

API reference

Inputs

CToggleGroup server inputs

Server inputs are passed in a template through <c-CToggleGroup ... /> or in Python through CToggleGroup(...).

InputTypeDefaultEffect
labelstrrequiredNames the related Toggle choices.
valuestr | None | Sequence[str] (CToggleValue)NoneSelects the initial single value or multiple values.
multipleboolFalseAllows several Toggles to be pressed together.
mandatoryboolFalsePrevents user activation from clearing the final pressed Toggle.
disabledboolFalseDisables every owned Toggle; enclosing CForm disabled remains dominant.
orientation"horizontal" | "vertical" (CToggleOrientation)"horizontal"Selects the group axis.
variant"soft" | "outline" | "plain" (CToggleVariant)"outline"Owns visual treatment for every grouped Toggle.
size"sm" | "md" | "lg" (CToggleSize)"md"Owns geometry for every grouped Toggle.
growboolFalseGives direct Toggles equal available width.
class_CClassValue | None (CClassValue)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted copied root attributes without replacing group ownership.

CToggleGroup client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CToggleGroup />.

InputTypeOmitted behaviorEffect
valuestring | null | string[] | undefinedUses the server input.Controls pressed values while supplied; omission releases ownership.
disabledboolean | undefinedUses the server input.Overrides local disabled while supplied; Form disabled remains dominant.
orientation"horizontal" | "vertical" | undefinedUses the server input.Overrides orientation while valid and supplied.
variant"soft" | "outline" | "plain" | undefinedUses the server input.Overrides visual treatment for every grouped Toggle.
size"sm" | "md" | "lg" | undefinedUses the server input.Overrides geometry for every grouped Toggle.
onValueChange((value, detail) => void) | undefinedUses the server input.Runs after an accepted grouped activation.

CToggle server inputs

Server inputs are passed in a template through <c-CToggle ... /> or in Python through CToggle(...).

InputTypeDefaultEffect
valuestr | NoneNoneRequired unique identity inside CToggleGroup; unused standalone.
pressedboolFalseSets standalone initial pressed state; group value owns grouped state.
disabledboolFalseDisables this Toggle; enclosing CForm disabled remains dominant.
variant"soft" | "outline" | "plain" | None (CToggleVariant)NoneSelects standalone visual treatment; CToggleGroup owns grouped presentation.
size"sm" | "md" | "lg" | None (CToggleSize)NoneSelects standalone geometry; CToggleGroup owns grouped presentation.
class_CClassValue | None (CClassValue)NoneAdds Button classes.
styleCStyleValue | None (CStyleValue)NoneAdds Button inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted copied Button attributes without replacing Toggle ownership.

CToggle client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CToggle />.

InputTypeOmitted behaviorEffect
pressedboolean | undefinedUses the server input.Controls a standalone Toggle while supplied.
disabledboolean | undefinedUses the server input.Overrides local disabled while supplied; enclosing CForm disabled remains dominant.
variant"soft" | "outline" | "plain" | undefinedUses the server input.Overrides standalone visual treatment; grouped presentation comes from CToggleGroup.
size"sm" | "md" | "lg" | undefinedUses the server input.Overrides standalone geometry; grouped presentation comes from CToggleGroup.
onPressedChange((pressed, detail) => void) | undefinedUses the server input.Runs after accepted standalone activation.

Slots

Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.

CToggleGroup slots

SlotRequiredDataFallback
defaultyes{} (CToggleGroupDefaultSlotData)None.

CToggle slots

SlotRequiredDataFallback
defaultyes{} (CToggleDefaultSlotData)None.

Events

Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.

CToggleGroup events

EventSignatureTrigger and timingDetailControlled and cancellation behavior
onValueChange(value, detail: CToggleValueChangeDetail) => void (CToggleValueChangeDetail)Accepted grouped activation.{value, previousValue, source} (CToggleValueChangeDetail)Reports the requested next selection; a supplied client value remains authoritative.

CToggle events

EventSignatureTrigger and timingDetailControlled and cancellation behavior
onPressedChange(pressed: boolean, detail: object) => voidAccepted standalone activation.{value: boolean, previousValue: boolean, source: "activation"}Reports the requested pressed state; a supplied client value remains authoritative.

Methods

-

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CToggle CSS variables

Apply these variables to CToggle or one of its ancestors.

VariableTypePurposeDefault
--cui-toggle-foregroundcolorResting text/icon foreground.CanvasText
--cui-toggle-backgroundcolorResting background.transparent
--cui-toggle-border-colorcolorBorder color.Nested-scheme border color.
--cui-toggle-pressed-backgroundcolorPressed background.Nested-scheme blue surface.
--cui-toggle-pressed-foregroundcolorPressed foreground.Nested-scheme blue foreground.
--cui-toggle-radiuslengthOuter group corners.0.55rem
--cui-toggle-heightlengthMinimum block size.Size-derived.
--cui-toggle-paddinglengthInline padding.Size-derived.
--cui-toggle-focus-ringcolorKeyboard focus outline.Highlight

CToggleGroup CSS variables

Apply these variables to CToggleGroup or one of its ancestors.

VariableTypePurposeDefault
--cui-toggle-group-gaplengthGap between Toggles.0

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CToggleGroup attributes

AttributeElementTypeMeaning
data-multipleRootpresent-or-absentPresent in multiple mode.
data-mandatoryRootpresent-or-absentPresent while final user deselection is prevented.
data-disabledRootpresent-or-absentPresent while all owned Toggles are disabled.
data-orientationRoot"horizontal" | "vertical"Reflects layout axis.
data-variantRoot"soft" | "outline" | "plain"Reflects group-owned visual treatment.
data-sizeRoot"sm" | "md" | "lg"Reflects group-owned geometry.
data-growRootpresent-or-absentPresent when Toggles share the available width.

CToggle attributes

AttributeElementTypeMeaning
aria-pressedNative ButtonbooleanExposes native Toggle pressed state.
data-pressedNative Buttonpresent-or-absentPublic pressed styling hook.
data-disabledNative Buttonpresent-or-absentMirrors effective disabled state.
data-valueGrouped native ButtonstringStable group identity.
data-variantNative Button"soft" | "outline" | "plain"Reflects visual treatment.
data-sizeNative Button"sm" | "md" | "lg"Reflects geometry.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CToggleGroup selectors

SelectorElementPurpose
[data-citry-ui-part="toggle-group"]RootStable group and attrs destination.

CToggle selectors

SelectorElementPurpose
[data-citry-ui-part="toggle"]Native Button rootStable Toggle, attrs, focus, and pressed-state surface.

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]
CToggleVariantLiteral["soft", "outline", "plain"]
CToggleSizeLiteral["sm", "md", "lg"]
CToggleOrientationLiteral["horizontal", "vertical"]
CToggleValuestr | None | Sequence[str]

CToggleValueChangeDetail

FieldTypeDefaultMeaning
valuestr | list[str] | None-Requested selection.
previousValuestr | list[str] | None-Selection before activation.
source"activation"-Change origin.

CToggleGroupDefaultSlotData

Empty dataclass: {}.

CToggleDefaultSlotData

Empty dataclass: {}.

Translation keys

-