List
Use CList and CListItem for concise semantic collections. Items can stay static, navigate, or act as native Buttons.
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
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".
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
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.
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
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
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
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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
ordered | bool | False | Renders ol instead of ul. |
start | int | None | None | Sets native ordered-list numbering start. |
reversed | bool | False | Reverses 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. |
divided | bool | False | Draws dividers between direct Items. |
label | str | None | None | Optionally names the list. |
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 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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
href | str | None | None | Makes the whole Item a native link; disabled Items render static content. |
action | bool | False | Makes the whole Item a native type=button action; cannot combine with href. |
disabled | bool | False | Removes link/action interaction and reflects disabled styling. |
current | bool | False | Emits aria-current=page on an enabled link. |
class_ | CClassValue | None (CClassValue) | None | Adds li classes. |
style | CStyleValue | None (CStyleValue) | None | Adds li inline styles. |
attrs | Mapping[str, object] | None | None | Adds copied li attributes without replacing Item semantics. |
surface_attrs | Mapping[str, object] | None | None | Adds 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
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CListDefaultSlotData) | None. |
CListItem slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
start | no | {} (CListItemStartSlotData) | No leading media. |
default | yes | {} (CListItemDefaultSlotData) | None. |
description | no | {} (CListItemDescriptionSlotData) | No supplemental text. |
end | no | {} (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.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-list-gap | length | Gap between direct Items. | 0.25rem |
--cui-list-padding | length | Root padding. | 0.35rem |
--cui-list-item-padding | length | Item surface padding. | Density-derived. |
--cui-list-radius | length | Item surface radius. | 0.65rem |
--cui-list-foreground | color | Primary foreground. | CanvasText |
--cui-list-muted | color | Description foreground. | Nested-scheme muted foreground. |
--cui-list-background | color | Root background. | transparent |
--cui-list-hover-background | color | Interactive hover and surface variant background. | Nested-scheme quiet surface. |
--cui-list-current-background | color | Current-link background. | Nested-scheme blue surface. |
--cui-list-divider-color | color | Divider color. | Nested-scheme border color. |
--cui-list-marker-color | color | Marker color. | currentColor |
--cui-list-focus-ring | color | Interactive focus outline. | Highlight |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CList attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-marker | List root | "none" | "disc" | "decimal" | Marker contract. |
data-density | List root | "comfortable" | "compact" | Spacing density. |
data-variant | List root | "plain" | "surface" | Surface treatment. |
data-divided | List root | present-or-absent | Present when direct Items have dividers. |
CListItem attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-current | li | present-or-absent | Present for the current link. |
data-disabled | li | present-or-absent | Present when a link becomes static or an action Button is natively disabled. |
data-interactive | li | present-or-absent | Present when the surface is an enabled link or Button. |
aria-current | Current 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
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="list"] | ul or ol root | Stable list and attrs destination. |
CListItem selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="list-item"] | li | Stable Item and attrs destination. |
[data-citry-ui-part="surface"] | div, a, or button | Stable content/action surface and surface_attrs destination. |
[data-citry-ui-part="start"] | Leading wrapper | Leading media surface. |
[data-citry-ui-part="body"] | Primary content wrapper | Primary and description layout surface. |
[data-citry-ui-part="description"] | Supplemental text wrapper | Muted description surface. |
[data-citry-ui-part="end"] | Trailing wrapper | Metadata or secondary action 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] |
CListMarker | Literal["none", "disc", "decimal"] |
CListDensity | Literal["comfortable", "compact"] |
CListVariant | Literal["plain", "surface"] |
CListDefaultSlotData
Empty dataclass: {}.
CListItemDefaultSlotData
Empty dataclass: {}.
CListItemStartSlotData
Empty dataclass: {}.
CListItemDescriptionSlotData
Empty dataclass: {}.
CListItemEndSlotData
Empty dataclass: {}.
Translation keys
-