Toggle
Use CToggle for a Button whose pressed state persists. Use CToggleGroup for related exclusive or multiple choices.
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
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
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.
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.
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
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
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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Names the related Toggle choices. |
value | str | None | Sequence[str] (CToggleValue) | None | Selects the initial single value or multiple values. |
multiple | bool | False | Allows several Toggles to be pressed together. |
mandatory | bool | False | Prevents user activation from clearing the final pressed Toggle. |
disabled | bool | False | Disables 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. |
grow | bool | False | Gives direct Toggles equal available width. |
class_ | CClassValue | None (CClassValue) | None | Adds root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds 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 />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
value | string | null | string[] | undefined | Uses the server input. | Controls pressed values while supplied; omission releases ownership. |
disabled | boolean | undefined | Uses the server input. | Overrides local disabled while supplied; Form disabled remains dominant. |
orientation | "horizontal" | "vertical" | undefined | Uses the server input. | Overrides orientation while valid and supplied. |
variant | "soft" | "outline" | "plain" | undefined | Uses the server input. | Overrides visual treatment for every grouped Toggle. |
size | "sm" | "md" | "lg" | undefined | Uses the server input. | Overrides geometry for every grouped Toggle. |
onValueChange | ((value, detail) => void) | undefined | Uses 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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
value | str | None | None | Required unique identity inside CToggleGroup; unused standalone. |
pressed | bool | False | Sets standalone initial pressed state; group value owns grouped state. |
disabled | bool | False | Disables this Toggle; enclosing CForm disabled remains dominant. |
variant | "soft" | "outline" | "plain" | None (CToggleVariant) | None | Selects standalone visual treatment; CToggleGroup owns grouped presentation. |
size | "sm" | "md" | "lg" | None (CToggleSize) | None | Selects standalone geometry; CToggleGroup owns grouped presentation. |
class_ | CClassValue | None (CClassValue) | None | Adds Button classes. |
style | CStyleValue | None (CStyleValue) | None | Adds Button inline styles. |
attrs | Mapping[str, object] | None | None | Adds 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 />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
pressed | boolean | undefined | Uses the server input. | Controls a standalone Toggle while supplied. |
disabled | boolean | undefined | Uses the server input. | Overrides local disabled while supplied; enclosing CForm disabled remains dominant. |
variant | "soft" | "outline" | "plain" | undefined | Uses the server input. | Overrides standalone visual treatment; grouped presentation comes from CToggleGroup. |
size | "sm" | "md" | "lg" | undefined | Uses the server input. | Overrides standalone geometry; grouped presentation comes from CToggleGroup. |
onPressedChange | ((pressed, detail) => void) | undefined | Uses 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
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CToggleGroupDefaultSlotData) | None. |
CToggle slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CToggleDefaultSlotData) | None. |
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CToggleGroup events
| Event | Signature | Trigger and timing | Detail | Controlled 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
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onPressedChange | (pressed: boolean, detail: object) => void | Accepted 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.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-toggle-foreground | color | Resting text/icon foreground. | CanvasText |
--cui-toggle-background | color | Resting background. | transparent |
--cui-toggle-border-color | color | Border color. | Nested-scheme border color. |
--cui-toggle-pressed-background | color | Pressed background. | Nested-scheme blue surface. |
--cui-toggle-pressed-foreground | color | Pressed foreground. | Nested-scheme blue foreground. |
--cui-toggle-radius | length | Outer group corners. | 0.55rem |
--cui-toggle-height | length | Minimum block size. | Size-derived. |
--cui-toggle-padding | length | Inline padding. | Size-derived. |
--cui-toggle-focus-ring | color | Keyboard focus outline. | Highlight |
CToggleGroup CSS variables
Apply these variables to CToggleGroup or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-toggle-group-gap | length | Gap between Toggles. | 0 |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CToggleGroup attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-multiple | Root | present-or-absent | Present in multiple mode. |
data-mandatory | Root | present-or-absent | Present while final user deselection is prevented. |
data-disabled | Root | present-or-absent | Present while all owned Toggles are disabled. |
data-orientation | Root | "horizontal" | "vertical" | Reflects layout axis. |
data-variant | Root | "soft" | "outline" | "plain" | Reflects group-owned visual treatment. |
data-size | Root | "sm" | "md" | "lg" | Reflects group-owned geometry. |
data-grow | Root | present-or-absent | Present when Toggles share the available width. |
CToggle attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
aria-pressed | Native Button | boolean | Exposes native Toggle pressed state. |
data-pressed | Native Button | present-or-absent | Public pressed styling hook. |
data-disabled | Native Button | present-or-absent | Mirrors effective disabled state. |
data-value | Grouped native Button | string | Stable group identity. |
data-variant | Native Button | "soft" | "outline" | "plain" | Reflects visual treatment. |
data-size | Native 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
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="toggle-group"] | Root | Stable group and attrs destination. |
CToggle selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="toggle"] | Native Button root | Stable Toggle, attrs, focus, and pressed-state surface. |
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] |
CToggleVariant | Literal["soft", "outline", "plain"] |
CToggleSize | Literal["sm", "md", "lg"] |
CToggleOrientation | Literal["horizontal", "vertical"] |
CToggleValue | str | None | Sequence[str] |
CToggleValueChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
value | str | list[str] | None | - | Requested selection. |
previousValue | str | list[str] | None | - | Selection before activation. |
source | "activation" | - | Change origin. |
CToggleGroupDefaultSlotData
Empty dataclass: {}.
CToggleDefaultSlotData
Empty dataclass: {}.
Translation keys
-