Theme
Version
GitHub PyPI Discord
On this page

Listbox

Use CListbox when the choices should remain visible while people compare and select them. Use Select or MultiSelect when the choices should open from a compact form control.

Listbox at a glance

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

citry.register_library(citry_ui)


class ListboxAtAGlance(Component):
    template = """
      <c-CListbox label="Choose a workspace" value="atlas" variant="soft">
        <c-CListboxOption value="atlas">
          <c-fill name="default">Atlas research</c-fill>
          <c-fill name="description">12 collaborators</c-fill>
          <c-fill name="end">Active</c-fill>
        </c-CListboxOption>
        <c-CListboxOption value="aurora">
          <c-fill name="default">Aurora field notes</c-fill>
          <c-fill name="description">7 collaborators</c-fill>
        </c-CListboxOption>
        <c-CListboxOption value="archive" disabled>Archived studies</c-CListboxOption>
      </c-CListbox>
    """


preview = ListboxAtAGlance()
preview  # noqa: B018

Select one value

Select one value
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class SingleSelection(Component):
    template = """
      <c-CListbox label="Density" value="comfortable" mandatory variant="outline">
        <c-CListboxOption value="compact">Compact</c-CListboxOption>
        <c-CListboxOption value="comfortable">Comfortable</c-CListboxOption>
        <c-CListboxOption value="spacious">Spacious</c-CListboxOption>
      </c-CListbox>
    """


preview = SingleSelection()
preview  # noqa: B018

Select several values

Select several values
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class MultipleSelection(Component):
    template = """
      <c-CListbox label="Include signals" multiple c-value="['temperature', 'humidity']" variant="outline">
        <c-CListboxOption value="temperature">Temperature</c-CListboxOption>
        <c-CListboxOption value="humidity">Humidity</c-CListboxOption>
        <c-CListboxOption value="pressure">Pressure</c-CListboxOption>
        <c-CListboxOption value="wind">Wind speed</c-CListboxOption>
      </c-CListbox>
    """


preview = MultipleSelection()
preview  # noqa: B018
Group options
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class GroupedOptions(Component):
    template = """
      <c-CListbox label="Choose a destination" value="prague">
        <c-CListboxGroup label="Europe">
          <c-CListboxOption value="prague">Prague</c-CListboxOption>
          <c-CListboxOption value="lisbon">Lisbon</c-CListboxOption>
        </c-CListboxGroup>
        <c-CListboxGroup label="Asia Pacific">
          <c-CListboxOption value="kyoto">Kyoto</c-CListboxOption>
          <c-CListboxOption value="wellington">Wellington</c-CListboxOption>
        </c-CListboxGroup>
      </c-CListbox>
    """


preview = GroupedOptions()
preview  # noqa: B018

Control selection

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

citry.register_library(citry_ui)


class ControlledListbox(Component):
    template = """
      <div x-data>
        <c-CListbox
          label="Review status"
          value="draft"
          $c-props="{
            value: $store.listboxExample.value,
            onValueChange: (next) => $store.listboxExample.value = next,
          }"
        >
          <c-CListboxOption value="draft">Draft</c-CListboxOption>
          <c-CListboxOption value="review">Ready for review</c-CListboxOption>
          <c-CListboxOption value="approved">Approved</c-CListboxOption>
        </c-CListbox>
        <p>Current: <strong x-text="$store.listboxExample.value"></strong></p>
      </div>
    """
    js = """
      Alpine.store('listboxExample', {value: 'draft'});
    """


preview = ControlledListbox()
preview  # noqa: B018

Disabled collections and options

Disable Listboxes and Options
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class DisabledListbox(Component):
    template = """
      <c-CStack gap="lg">
        <c-CListbox label="Deployment region" value="eu" variant="outline">
          <c-CListboxOption value="eu">Europe</c-CListboxOption>
          <c-CListboxOption value="us" disabled>United States β€” unavailable</c-CListboxOption>
          <c-CListboxOption value="apac">Asia Pacific</c-CListboxOption>
        </c-CListbox>
        <c-CListbox label="Locked policy" value="strict" disabled variant="soft">
          <c-CListboxOption value="standard">Standard</c-CListboxOption>
          <c-CListboxOption value="strict">Strict</c-CListboxOption>
        </c-CListbox>
      </c-CStack>
    """


preview = DisabledListbox()
preview  # noqa: B018

Keyboard navigation

Down and Up move between enabled Options. Home and End jump to the collection edges, printable text performs buffered typeahead, Enter or Space selects, and Escape clears a non-mandatory selection.

Navigate a Listbox
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class KeyboardListbox(Component):
    template = """
      <c-CListbox label="Jump to a city" value="brno" loop variant="outline">
        <c-CListboxOption value="brno">Brno</c-CListboxOption>
        <c-CListboxOption value="budapest">Budapest</c-CListboxOption>
        <c-CListboxOption value="krakow">KrakΓ³w</c-CListboxOption>
        <c-CListboxOption value="prague">Prague</c-CListboxOption>
        <c-CListboxOption value="vienna">Vienna</c-CListboxOption>
      </c-CListbox>
    """


preview = KeyboardListbox()
preview  # noqa: B018

Customize Listbox

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

citry.register_library(citry_ui)


class CustomizedListbox(Component):
    css = """
      .copper-listbox {
        --cui-listbox-radius: 1.1rem;
        --cui-listbox-selected-background: light-dark(#7c2d12, #fed7aa);
        --cui-listbox-selected-foreground: light-dark(#fff7ed, #431407);
        --cui-listbox-border-color: light-dark(#c2410c, #fdba74);
        --cui-listbox-option-padding: 0.7rem 0.8rem;
      }
    """
    template = """
      <c-CListbox label="Finish" value="copper" class_="copper-listbox" variant="outline">
        <c-CListboxOption value="copper">
          <c-fill name="start"><span aria-hidden="true">β—†</span></c-fill>
          <c-fill name="default">Burnished copper</c-fill>
          <c-fill name="description">Warm and tactile</c-fill>
        </c-CListboxOption>
        <c-CListboxOption value="slate">Deep slate</c-CListboxOption>
        <c-CListboxOption value="linen">Soft linen</c-CListboxOption>
      </c-CListbox>
    """


preview = CustomizedListbox()
preview  # noqa: B018

Accessibility and behavior

The named collection uses role="listbox"; Options use role="option", and visible group labels name role="group" collections. One enabled Option is in the Tab order. Focus and selection remain separate, and disabled Options are skipped by keyboard navigation.

CListbox is a persistent application selection surface, not a form control. Use Select or MultiSelect when native form submission, reset, validity, or a compact popup is required.

API reference

Inputs

CListbox server inputs

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

InputTypeDefaultEffect
labelstrrequiredSupplies the visible accessible Listbox name.
valuestr | None | Sequence[str] (CListboxValue)NoneSets initial single or multiple selection.
multipleboolFalseEnables independent multiple selection.
mandatoryboolFalsePrevents user interaction from clearing the final selected Option.
disabledboolFalseDisables focus and selection throughout the collection.
loopboolFalseWraps arrow navigation at collection edges.
variant"plain" | "soft" | "outline" (CListboxVariant)"outline"Selects surface treatment.
size"sm" | "md" | "lg" (CListboxSize)"md"Selects Option geometry.
class_CClassValue | None (CClassValue)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted root attributes without replacing owned state structure or runtime.
listbox_attrsMapping[str, object] | NoneNoneAdds trusted attributes to the role listbox surface without replacing owned semantics or focus.

CListbox client inputs

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

InputTypeOmitted behaviorEffect
valuestring | string[] | nullReleases control to committed selection.Controls single or multiple selection while supplied.
mandatoryboolUses the server value.Reactively prevents the final user-selected value from clearing.
disabledboolUses the server value.Reactively disables collection interaction.
loopboolUses the server value.Reactively changes arrow wrapping.
variant"plain" | "soft" | "outline" (CListboxVariant)Uses the server value.Reactively changes surface treatment.
size"sm" | "md" | "lg" (CListboxSize)Uses the server value.Reactively changes Option geometry.
onValueChange((value: string | string[] | null, detail: CListboxValueChangeDetail) => void) | undefinedNo component callback runs.Receives selection and structural-recovery requests.

CListboxOption server inputs

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

InputTypeDefaultEffect
valuestrrequiredSupplies stable unique Option identity.
disabledboolFalsePrevents focus and selection for this Option.
text_valuestr | NoneNoneOverrides normalized visible label text for typeahead.
class_CClassValue | None (CClassValue)NoneAdds classes to the concrete Option.
styleCStyleValue | None (CStyleValue)NoneAdds inline styles to the concrete Option.
attrsMapping[str, object] | NoneNoneAdds trusted Option attributes without replacing semantics identity focus or state.

CListboxOption client inputs

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

InputTypeOmitted behaviorEffect
disabledboolUses the server value.Reactively disables this Option.
textValuestring | nullUses the server value or visible label.Reactively changes typeahead text.

CListboxGroup server inputs

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

InputTypeDefaultEffect
labelstrrequiredSupplies the visible accessible group name.
class_CClassValue | None (CClassValue)NoneAdds classes to the group.
styleCStyleValue | None (CStyleValue)NoneAdds inline styles to the group.
attrsMapping[str, object] | NoneNoneAdds trusted group attributes without replacing owned semantics or label relationship.

Slots

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

CListbox slots

SlotRequiredDataFallback
defaultyes{} (CListboxDefaultSlotData)None. Accepts direct CListboxOption or CListboxGroup declarations.

CListboxOption slots

SlotRequiredDataFallback
defaultyes{value} (CListboxOptionDefaultSlotData)None. Supplies visible accessible label content.
startno{value, selected, disabled} (CListboxOptionStateSlotData)Omitted. Decorative leading content.
descriptionno{value} (CListboxOptionDescriptionSlotData)Omitted. Supplies separately described supporting text.
endno{value, selected, disabled} (CListboxOptionStateSlotData)Omitted. Decorative trailing content.

CListboxGroup slots

SlotRequiredDataFallback
defaultyes{} (CListboxGroupDefaultSlotData)None. Accepts one or more direct CListboxOption declarations.

Events

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

CListbox events

EventSignatureTrigger and timingDetailControlled and cancellation behavior
onValueChange(value: string | string[] | null, detail: CListboxValueChangeDetail) => void (CListboxValueChangeDetail)Enabled pointer or keyboard selection request or settled structural recovery.{value, previousValue, option, selected, controlled, source, sourceEvent} (CListboxValueChangeDetail)Commits immediately when uncontrolled and waits for owner acceptance when controlled.

Methods

-

CSS

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

CListbox CSS variables

Apply these variables to CListbox or one of its ancestors.

VariableTypePurposeDefault
--cui-listbox-gaplengthGap between label and collection.0.375rem
--cui-listbox-max-block-sizelengthMaximum scrollable collection height.18rem
--cui-listbox-backgroundcolorCollection background.variant-derived Canvas surface
--cui-listbox-foregroundcolorCollection foreground.CanvasText
--cui-listbox-muted-colorcolorDisabled and secondary foreground.light #667085; dark #a4a7ae
--cui-listbox-border-colorcolorOutline border.light #d0d5dd; dark #535862
--cui-listbox-hover-backgroundcolorEnabled hover surface.7% CanvasText mix
--cui-listbox-selected-backgroundcolorSelected Option surface.light #dbeafe; dark #1e3a5f
--cui-listbox-selected-foregroundcolorSelected Option foreground.light #1849a9; dark #d1e9ff
--cui-listbox-focus-colorcolorRoving focus outline.Highlight
--cui-listbox-radiuslengthCollection corner radius.0.625rem
--cui-listbox-option-paddinglengthOption block and inline padding.size-derived

Attributes

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

CListbox attributes

AttributeElementTypeMeaning
roleCollection divlistboxDeclares the persistent selection widget.
roleOption divoptionDeclares each selectable value.
roleGroup divgroupGroups related Options under a visible label.
aria-labelledbyCollection Option or Group divIDREFConnects each semantic owner to its visible label.
aria-selectedOption divtrue | falseReflects effective selection.
aria-disabledCollection or Option divtrue | falseReflects effective unavailability.
aria-multiselectableCollection divtruePresent only in multiple mode.
tabindexOption div0 | -1Implements one enabled roving Tab stop.
data-selectedOption divpresent-or-absentMirrors selected styling state.
data-activeOption divpresent-or-absentMirrors roving focus identity.
data-disabledRoot or Option divpresent-or-absentMirrors effective unavailability.
data-valueOption divstringExposes canonical Option identity.
data-multipleRoot divpresent-or-absentMirrors multiple selection mode.
data-mandatoryRoot divpresent-or-absentMirrors final-selection protection.
data-variantRoot divplain | soft | outlineMirrors effective surface treatment.
data-sizeRoot divsm | md | lgMirrors effective geometry.

Selectors

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

CListbox selectors

SelectorElementPurpose
[data-citry-ui-part="listbox-root"]Root divStable root attrs and state surface.
[data-citry-ui-part="listbox-label"]Label spanVisible collection label.
[data-citry-ui-part="listbox"]Collection divSemantic and scrolling selection surface.
[data-citry-ui-part="listbox-option"]Option divStable Option attrs focus and state surface.
[data-citry-ui-part="listbox-indicator"]Indicator spanDecorative selected-state mark.
[data-citry-ui-part="listbox-option-start"]Start spanDecorative leading content wrapper.
[data-citry-ui-part="listbox-option-copy"]Copy spanStable label and description layout wrapper.
[data-citry-ui-part="listbox-option-label"]Label spanVisible Option name and default typeahead source.
[data-citry-ui-part="listbox-option-description"]Description spanSeparately described supporting text.
[data-citry-ui-part="listbox-option-end"]End spanDecorative trailing content wrapper.
[data-citry-ui-part="listbox-group"]Group divStable semantic grouping surface.
[data-citry-ui-part="listbox-group-label"]Group label spanVisible group name.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, object] | Sequence[CStyleValue]
CListboxValuestr | None | Sequence[str]
CListboxVariantLiteral["plain", "soft", "outline"]
CListboxSizeLiteral["sm", "md", "lg"]
CListboxChangeSourceLiteral["pointer", "keyboard", "structure"]

CListboxDefaultSlotData

Empty dataclass: {}.

CListboxGroupDefaultSlotData

Empty dataclass: {}.

CListboxOptionDefaultSlotData

FieldTypeDefaultMeaning
valuestr-Canonical Option identity.

CListboxOptionStateSlotData

FieldTypeDefaultMeaning
valuestr-Canonical Option identity.
selectedbool-Server-rendered initial selected state.
disabledbool-Server-rendered initial Option disabled state.

CListboxOptionDescriptionSlotData

FieldTypeDefaultMeaning
valuestr-Canonical Option identity.

CListboxValueChangeDetail

FieldTypeDefaultMeaning
valuestr | list[str] | None-Requested next effective value.
previousValuestr | list[str] | None-Prior effective value.
optionHTMLElement | None-Changed Option or None for structural recovery.
selectedbool-Whether the Option is requested selected.
controlledbool-Whether the client value currently controls selection.
source"pointer" | "keyboard" | "structure" (CListboxChangeSource)-Request source.
sourceEventEvent | None-Native source event or None for structure.

Translation keys

-