Timeline
Use CTimeline and CTimelineItem for ordered histories, activity feeds, roadmaps, and status sequences. Timeline is presentational: links, actions, loading, and date formatting remain owned by your application.
Timeline at a glance
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineAtAGlance(Component):
template = """
<c-CTimeline label="Shipment progress">
<c-CTimelineItem state="complete">
<c-fill name="opposite"><time datetime="2026-08-18">18 Aug</time></c-fill>
<c-fill name="default"><strong>Order confirmed</strong><br />Payment received</c-fill>
</c-CTimelineItem>
<c-CTimelineItem state="current">
<c-fill name="opposite"><time datetime="2026-08-21">Today</time></c-fill>
<c-fill name="default"><strong>In transit</strong><br />Departed the regional hub</c-fill>
</c-CTimelineItem>
<c-CTimelineItem state="pending"><strong>Delivered</strong></c-CTimelineItem>
</c-CTimeline>
"""
preview = TimelineAtAGlance()
preview # noqa: B018
Present an activity feed
Place semantic <time> elements, headings, descriptions, links, and actions inside each Item. The authored DOM order remains the reading order.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineActivity(Component):
template = """
<c-CTimeline label="Repository activity" density="compact">
<c-CTimelineItem>
<c-fill name="opposite"><time datetime="2026-08-21T09:15:00Z">09:15</time></c-fill>
<c-fill name="default">
<strong>Mina opened pull request #184</strong><p>Improve invoice import diagnostics.</p>
</c-fill>
</c-CTimelineItem>
<c-CTimelineItem>
<c-fill name="opposite"><time datetime="2026-08-21T10:04:00Z">10:04</time></c-fill>
<c-fill name="default"><strong>Leo approved the changes</strong><p>All required checks passed.</p></c-fill>
</c-CTimelineItem>
<c-CTimelineItem state="current">
<c-fill name="opposite"><time datetime="2026-08-21T10:12:00Z">10:12</time></c-fill>
<c-fill name="default">
<strong>Ready to merge</strong><p><a href="#review">Review the final diff</a></p>
</c-fill>
</c-CTimelineItem>
</c-CTimeline>
"""
css = ":where(.cui-timeline__content p){margin:.25rem 0 0}"
preview = TimelineActivity()
preview # noqa: B018
Communicate status in text
Item state styles the indicator. It never replaces a written status: the indicator is decorative, and only one Item may be current.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineStatus(Component):
template = """
<c-CTimeline label="Deployment status" line_style="dashed">
<c-CTimelineItem state="complete">
<strong>Build completed</strong><br />Artifacts signed successfully
</c-CTimelineItem>
<c-CTimelineItem state="error">
<strong>Staging failed</strong><br />Health check timed out
</c-CTimelineItem>
<c-CTimelineItem state="current">
<strong>Retry in progress</strong><br />Current attempt is running
</c-CTimelineItem>
<c-CTimelineItem state="pending">
<strong>Production pending</strong><br />Waiting for staging approval
</c-CTimelineItem>
</c-CTimeline>
"""
preview = TimelineStatus()
preview # noqa: B018
Alternate content around the track
Use side="alternate" for a centered vertical track. An Item can override its resolved side with side="start" or side="end".
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineAlternating(Component):
template = """
<c-CTimeline label="Product history" side="alternate">
<c-CTimelineItem state="complete">
<strong>Prototype</strong><p>The first field trial validated the core workflow.</p>
</c-CTimelineItem>
<c-CTimelineItem state="complete">
<strong>Private beta</strong><p>Design partners shaped the collaboration model.</p>
</c-CTimelineItem>
<c-CTimelineItem state="current">
<strong>Public beta</strong><p>The current release focuses on reliability and polish.</p>
</c-CTimelineItem>
<c-CTimelineItem state="pending">
<strong>General availability</strong><p>Operational review and migration guidance remain.</p>
</c-CTimelineItem>
</c-CTimeline>
"""
css = ":where(.cui-timeline__content p){margin:.25rem 0 0}"
preview = TimelineAlternating()
preview # noqa: B018
Build a horizontal roadmap
Horizontal Timelines preserve chronological DOM order and scroll within their own bounds at narrow widths.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineHorizontal(Component):
template = """
<c-CTimeline label="2026 roadmap" orientation="horizontal" side="alternate" size="lg">
<c-CTimelineItem state="complete"><strong>Q1</strong><br />Unified accounts</c-CTimelineItem>
<c-CTimelineItem state="complete"><strong>Q2</strong><br />Regional storage</c-CTimelineItem>
<c-CTimelineItem state="current"><strong>Q3</strong><br />Audit workspaces</c-CTimelineItem>
<c-CTimelineItem state="pending"><strong>Q4</strong><br />Policy automation</c-CTimelineItem>
</c-CTimeline>
"""
preview = TimelineHorizontal()
preview # noqa: B018
Customize indicators and the track
Use the indicator slot for an icon, avatar, or authored marker and public CSS variables for geometry and color. Indicator content is hidden from assistive technology, so repeat its meaning in the Item's visible content.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimelineCustomization(Component):
template = """
<div class="custom-timeline">
<c-CTimeline label="Team activity"
c-style="{'--cui-timeline-indicator-size':'2rem','--cui-timeline-track-size':'2.75rem'}">
<c-CTimelineItem>
<c-fill name="indicator"><span class="avatar">AK</span></c-fill>
<c-fill name="default">
<strong>Ada assigned the issue</strong><br />Ownership moved to Platform.
</c-fill>
</c-CTimelineItem>
<c-CTimelineItem state="current">
<c-fill name="indicator"><span class="avatar">JM</span></c-fill>
<c-fill name="default">
<strong>Jules is investigating</strong><br />Current work is linked in the incident log.
</c-fill>
</c-CTimelineItem>
</c-CTimeline>
</div>
"""
css = """
:where(.custom-timeline) { --cui-timeline-current-color:#7c3aed; }
:where(.custom-timeline .avatar) {
display:grid;
inline-size:100%;
block-size:100%;
place-items:center;
border-radius:50%;
background:currentcolor;
color:Canvas;
font-size:.65rem;
font-weight:800;
}
"""
preview = TimelineCustomization()
preview # noqa: B018
Timeline or Stepper?
Use Timeline to read events or history. Use Stepper when the user is moving through a finite workflow and the component owns a current step or optional step navigation.
Accessibility and localization
Timeline renders one ordered list with one list item per event. It adds no focus target or Arrow-key behavior. An Item with state="current" receives aria-current="true"; all other state meaning must be written in content.
Timeline owns no text or date formatting and therefore has no catalog keys. Author localized content with ordinary Citry tr() or $c-tr, render dates with your application's locale profile, and add explicit dir boundaries when mixing directional content.
API reference
Inputs
CTimeline server inputs
Server inputs are passed in a template through <c-CTimeline ... /> or in Python through CTimeline(...).
| Input | Type | Default | Effect |
|---|---|---|---|
orientation | CTimelineOrientation (CTimelineOrientation) | "vertical" | Selects a vertical or horizontal track axis. |
side | CTimelineSide (CTimelineSide) | "end" | Places Item content at the logical end start or alternating sides of the track. |
line_style | CTimelineLineStyle (CTimelineLineStyle) | "solid" | Selects solid or dashed connectors. |
density | CTimelineDensity (CTimelineDensity) | "comfortable" | Selects comfortable or compact spacing. |
size | CTimelineSize (CTimelineSize) | "md" | Selects coordinated indicator and track geometry. |
label | str | None | None | Optionally supplies the ordered list accessible name. |
class_ | CClassValue | None (CClassValue) | None | Adds classes to the root ordered list. |
style | CStyleValue | None (CStyleValue) | None | Adds styles to the root ordered list. |
attrs | Mapping[str, object] | None | None | Adds copied allowed attributes without replacing owned semantics or state. |
CTimelineItem server inputs
Server inputs are passed in a template through <c-CTimelineItem ... /> or in Python through CTimelineItem(...).
| Input | Type | Default | Effect |
|---|---|---|---|
state | CTimelineState (CTimelineState) | "neutral" | Styles authored neutral complete current pending or error status; current adds aria-current. |
side | CTimelineItemSide (CTimelineItemSide) | "auto" | Uses the root-resolved side or overrides one Item to logical start or end. |
class_ | CClassValue | None (CClassValue) | None | Adds classes to the rendered list item. |
style | CStyleValue | None (CStyleValue) | None | Adds styles to the rendered list item. |
attrs | Mapping[str, object] | None | None | Adds copied allowed list-item attributes without replacing owned semantics or state. |
Slots
Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.
CTimeline slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CTimelineDefaultSlotData) | None; one or more CTimelineItem declarations are required. |
CTimelineItem slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {index, state, side, is_first, is_last} (CTimelineItemDefaultSlotData) | None. |
opposite | no | {index, state, side, is_first, is_last} (CTimelineItemOppositeSlotData) | Omitted. |
indicator | no | {index, state, side, is_first, is_last} (CTimelineItemIndicatorSlotData) | Decorative dot. |
Events
-
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CTimeline CSS variables
Apply these variables to CTimeline or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-timeline-gap | length | Minimum space along the sequence axis. | 1.5rem; compact 0.75rem |
--cui-timeline-item-gap | length | Space between the track and authored content. | 0.75rem; compact 0.5rem |
--cui-timeline-track-size | length | Cross-axis track lane size. | sm 1.5rem; md 2rem; lg 2.5rem |
--cui-timeline-indicator-size | length | Indicator inline and block size. | sm 0.5rem; md 0.75rem; lg 1rem |
--cui-timeline-line-width | length | Connector and indicator border thickness. | 0.125rem |
--cui-timeline-line-color | color | Connector color. | Adaptive neutral |
--cui-timeline-indicator-color | color | Neutral indicator color. | Adaptive neutral |
--cui-timeline-current-color | color | Current indicator color. | Adaptive blue |
--cui-timeline-complete-color | color | Complete indicator color. | Adaptive green |
--cui-timeline-pending-color | color | Pending indicator color. | Adaptive muted neutral |
--cui-timeline-error-color | color | Error indicator color. | Adaptive red |
--cui-timeline-muted-color | color | Opposite metadata color. | Adaptive neutral |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CTimeline attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
aria-label | Root ol | string | Optional accessible name. |
data-orientation | Root ol | CTimelineOrientation (CTimelineOrientation) | Mirrors the track axis. |
data-side | Root ol | CTimelineSide (CTimelineSide) | Mirrors root placement policy. |
data-line-style | Root ol | CTimelineLineStyle (CTimelineLineStyle) | Mirrors connector treatment. |
data-density | Root ol | CTimelineDensity (CTimelineDensity) | Mirrors spacing density. |
data-size | Root ol | CTimelineSize (CTimelineSize) | Mirrors geometry size. |
CTimelineItem attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-index | Item li | nonnegative-integer-string | Exposes settled zero-based order. |
data-state | Item li | CTimelineState (CTimelineState) | Mirrors authored visual status. |
data-side | Item li | start | end | Mirrors resolved logical placement. |
data-has-opposite | Item li | present | absent | Marks an authored opposite slot. |
aria-current | Current Item li | true | Identifies the one current event. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CTimeline selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="timeline"] | Root ol | State reflections and root customization destination. |
[data-citry-ui-part="item"] | Item li | Item attrs state and customization destination. |
[data-citry-ui-part="opposite"] | Optional metadata div | Dates and other opposite content. |
[data-citry-ui-part="track"] | Decorative div | Owns connector segments and indicator. |
[data-citry-ui-part="before"] | Decorative span | Connector segment before the indicator. |
[data-citry-ui-part="indicator"] | Decorative span | Default dot or custom indicator destination. |
[data-citry-ui-part="after"] | Decorative span | Connector segment after the indicator. |
[data-citry-ui-part="content"] | Content div | Authored event content destination. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CTimelineOrientation | Literal["vertical", "horizontal"] |
CTimelineSide | Literal["start", "end", "alternate"] |
CTimelineItemSide | Literal["auto", "start", "end"] |
CTimelineLineStyle | Literal["solid", "dashed"] |
CTimelineDensity | Literal["comfortable", "compact"] |
CTimelineSize | Literal["sm", "md", "lg"] |
CTimelineState | Literal["neutral", "complete", "current", "pending", "error"] |
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, object] | Sequence[CStyleValue] |
CTimelineDefaultSlotData
Empty dataclass: {}.
CTimelineItemDefaultSlotData
| Field | Type | Default | Meaning |
|---|---|---|---|
index | int | - | Settled zero-based Item index. |
state | CTimelineState (CTimelineState) | - | Authored Item state. |
side | start | end | - | Resolved logical content side. |
is_first | bool | - | Whether this is the first Item. |
is_last | bool | - | Whether this is the last Item. |
Input type aliases
| Interface | Definition |
|---|---|
CTimelineItemOppositeSlotData | CTimelineItemDefaultSlotData |
Input type aliases
| Interface | Definition |
|---|---|
CTimelineItemIndicatorSlotData | CTimelineItemDefaultSlotData |
Translation keys
-