Theme
Version
GitHub PyPI Discord
On this page

List

Use CList and CListItem for concise semantic collections. Items can stay static, navigate, or act as native Buttons.

List at a glance

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

citry.register_library(citry_ui)


class ListGlance(Component):
    template = """
      <c-CList label="Recent observations" variant="surface" c-divided="True">
        <c-CListItem href="/observations/aurora" c-current="True">Aurora over TromsΓΈ</c-CListItem>
        <c-CListItem href="/observations/comet">Comet C/2026 Q2</c-CListItem>
        <c-CListItem href="/observations/eclipse">Lunar eclipse</c-CListItem>
      </c-CList>
    """


preview = ListGlance()
preview  # noqa: B018

Present semantic content

Present semantic list content
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ListContent(Component):
    template = """
      <c-CList c-ordered="True" marker="decimal" c-start="3">
        <c-CListItem>Align the telescope</c-CListItem>
        <c-CListItem>Calibrate the camera</c-CListItem>
        <c-CListItem>Begin the exposure</c-CListItem>
      </c-CList>
    """


preview = ListContent()
preview  # noqa: B018

Build navigation

Set href on an Item for a whole-row link. current=True adds aria-current="page".

Build list navigation
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ListNavigation(Component):
    template = """
      <nav aria-label="Observatory">
        <c-CList variant="surface">
          <c-CListItem href="/sky" c-current="True">Sky map</c-CListItem>
          <c-CListItem href="/sessions">Sessions</c-CListItem>
          <c-CListItem href="/equipment">Equipment</c-CListItem>
        </c-CList>
      </nav>
    """


preview = ListNavigation()
preview  # noqa: B018

Add media, descriptions, and trailing content

Compose List Item anatomy
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ListAnatomy(Component):
    template = """
      <c-CList label="Specimens" c-divided="True">
        <c-CListItem>
          <c-fill name="start"><c-CAvatar alt="Mare Imbrium" /></c-fill>
          <c-fill name="default">Mare Imbrium basalt</c-fill>
          <c-fill name="description">Apollo 15 Β· sample 15555</c-fill>
          <c-fill name="end"><c-CBadge variant="outline">Lunar</c-CBadge></c-fill>
        </c-CListItem>
        <c-CListItem>
          <c-fill name="start"><c-CIcon name="star" /></c-fill>
          <c-fill name="default">Murchison meteorite</c-fill>
          <c-fill name="description">Carbonaceous chondrite Β· 1969</c-fill>
          <c-fill name="end">12.4 g</c-fill>
        </c-CListItem>
      </c-CList>
    """


preview = ListAnatomy()
preview  # noqa: B018

Add whole-row and secondary actions

Use action=True for one whole-row Button. Keep an Item static when its end slot contains a separate control.

Compose List actions
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ListActions(Component):
    template = """
      <c-CList label="Observation queue" variant="surface">
        <c-CListItem c-action="True" @click="console.log('opened')">Open current session</c-CListItem>
        <c-CListItem>
          <c-fill name="default">Nightly calibration</c-fill>
          <c-fill name="description">Ready to archive</c-fill>
          <c-fill name="end"><c-CButton size="sm" variant="outline">Archive</c-CButton></c-fill>
        </c-CListItem>
      </c-CList>
    """


preview = ListActions()
preview  # noqa: B018

Nest Lists

Nest semantic Lists
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class NestedList(Component):
    template = """
      <c-CList label="Solar system" marker="disc">
        <c-CListItem>
          <c-fill name="default">
            Inner planets
            <c-CList marker="disc">
              <c-CListItem>Mercury</c-CListItem>
              <c-CListItem>Venus</c-CListItem>
              <c-CListItem>Earth</c-CListItem>
            </c-CList>
          </c-fill>
        </c-CListItem>
        <c-CListItem>Outer planets</c-CListItem>
      </c-CList>
    """


preview = NestedList()
preview  # noqa: B018

Choose density and dividers

Choose List presentation
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ListPresentation(Component):
    template = """
      <c-CStack gap="lg">
        <c-CList label="Comfortable list" variant="surface">
          <c-CListItem>Andromeda Galaxy</c-CListItem>
          <c-CListItem>Triangulum Galaxy</c-CListItem>
        </c-CList>
        <c-CList label="Compact divided list" density="compact" c-divided="True">
          <c-CListItem>Whirlpool Galaxy</c-CListItem>
          <c-CListItem>Sombrero Galaxy</c-CListItem>
        </c-CList>
      </c-CStack>
    """


preview = ListPresentation()
preview  # noqa: B018

Customize List

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

citry.register_library(citry_ui)


class ListCustomization(Component):
    template = """
      <c-CList class_="violet-list" label="Nebula catalog" variant="surface">
        <c-CListItem href="/nebula/orion" c-current="True">Orion Nebula</c-CListItem>
        <c-CListItem href="/nebula/lagoon">Lagoon Nebula</c-CListItem>
      </c-CList>
    """
    css = """
      :where(.violet-list) {
        --cui-list-current-background: light-dark(#ede9fe, #4c1d95);
        --cui-list-radius: 1rem;
      }
    """


preview = ListCustomization()
preview  # noqa: B018

Accessibility and behavior

Lists retain native ul/ol and li semantics. Only links, whole-row Buttons, and authored secondary controls enter Tab order. Use Menu for command popovers, Tabs for view switching, and DataTable for two-dimensional records.

API reference

Inputs

CList server inputs

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

InputTypeDefaultEffect
orderedboolFalseRenders ol instead of ul.
startint | NoneNoneSets native ordered-list numbering start.
reversedboolFalseReverses native ordered-list numbering.
marker"none" | "disc" | "decimal" (CListMarker)"none"Selects no marker or a semantic unordered/ordered marker.
density"comfortable" | "compact" (CListDensity)"comfortable"Selects item spacing.
variant"plain" | "surface" (CListVariant)"plain"Selects transparent or quiet item surfaces.
dividedboolFalseDraws dividers between direct Items.
labelstr | NoneNoneOptionally names the list.
class_CClassValue | None (CClassValue)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted copied list attributes without replacing semantics, children, or runtime fields.

CListItem server inputs

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

InputTypeDefaultEffect
hrefstr | NoneNoneMakes the whole Item a native link; disabled Items render static content.
actionboolFalseMakes the whole Item a native type=button action; cannot combine with href.
disabledboolFalseRemoves link/action interaction and reflects disabled styling.
currentboolFalseEmits aria-current=page on an enabled link.
class_CClassValue | None (CClassValue)NoneAdds li classes.
styleCStyleValue | None (CStyleValue)NoneAdds li inline styles.
attrsMapping[str, object] | NoneNoneAdds copied li attributes without replacing Item semantics.
surface_attrsMapping[str, object] | NoneNoneAdds copied static/link/Button surface attributes without replacing its identity or behavior.

Slots

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

CList slots

SlotRequiredDataFallback
defaultyes{} (CListDefaultSlotData)None.

CListItem slots

SlotRequiredDataFallback
startno{} (CListItemStartSlotData)No leading media.
defaultyes{} (CListItemDefaultSlotData)None.
descriptionno{} (CListItemDescriptionSlotData)No supplemental text.
endno{} (CListItemEndSlotData)No trailing metadata or secondary action.

Events

-

Methods

-

CSS

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

CList CSS variables

Apply these variables to CList or one of its ancestors.

VariableTypePurposeDefault
--cui-list-gaplengthGap between direct Items.0.25rem
--cui-list-paddinglengthRoot padding.0.35rem
--cui-list-item-paddinglengthItem surface padding.Density-derived.
--cui-list-radiuslengthItem surface radius.0.65rem
--cui-list-foregroundcolorPrimary foreground.CanvasText
--cui-list-mutedcolorDescription foreground.Nested-scheme muted foreground.
--cui-list-backgroundcolorRoot background.transparent
--cui-list-hover-backgroundcolorInteractive hover and surface variant background.Nested-scheme quiet surface.
--cui-list-current-backgroundcolorCurrent-link background.Nested-scheme blue surface.
--cui-list-divider-colorcolorDivider color.Nested-scheme border color.
--cui-list-marker-colorcolorMarker color.currentColor
--cui-list-focus-ringcolorInteractive focus outline.Highlight

Attributes

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

CList attributes

AttributeElementTypeMeaning
data-markerList root"none" | "disc" | "decimal"Marker contract.
data-densityList root"comfortable" | "compact"Spacing density.
data-variantList root"plain" | "surface"Surface treatment.
data-dividedList rootpresent-or-absentPresent when direct Items have dividers.

CListItem attributes

AttributeElementTypeMeaning
data-currentlipresent-or-absentPresent for the current link.
data-disabledlipresent-or-absentPresent when a link becomes static or an action Button is natively disabled.
data-interactivelipresent-or-absentPresent when the surface is an enabled link or Button.
aria-currentCurrent link"page"Exposes current navigation location.

Selectors

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

CList selectors

SelectorElementPurpose
[data-citry-ui-part="list"]ul or ol rootStable list and attrs destination.

CListItem selectors

SelectorElementPurpose
[data-citry-ui-part="list-item"]liStable Item and attrs destination.
[data-citry-ui-part="surface"]div, a, or buttonStable content/action surface and surface_attrs destination.
[data-citry-ui-part="start"]Leading wrapperLeading media surface.
[data-citry-ui-part="body"]Primary content wrapperPrimary and description layout surface.
[data-citry-ui-part="description"]Supplemental text wrapperMuted description surface.
[data-citry-ui-part="end"]Trailing wrapperMetadata or secondary action 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]
CListMarkerLiteral["none", "disc", "decimal"]
CListDensityLiteral["comfortable", "compact"]
CListVariantLiteral["plain", "surface"]

CListDefaultSlotData

Empty dataclass: {}.

CListItemDefaultSlotData

Empty dataclass: {}.

CListItemStartSlotData

Empty dataclass: {}.

CListItemDescriptionSlotData

Empty dataclass: {}.

CListItemEndSlotData

Empty dataclass: {}.

Translation keys

-