Theme
Version
GitHub PyPI Discord
On this page

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

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.

Present an activity feed
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.

Present status history
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".

Build an alternating Timeline
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.

Build a horizontal roadmap
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.

Customize Timeline
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(...).

InputTypeDefaultEffect
orientationCTimelineOrientation (CTimelineOrientation)"vertical"Selects a vertical or horizontal track axis.
sideCTimelineSide (CTimelineSide)"end"Places Item content at the logical end start or alternating sides of the track.
line_styleCTimelineLineStyle (CTimelineLineStyle)"solid"Selects solid or dashed connectors.
densityCTimelineDensity (CTimelineDensity)"comfortable"Selects comfortable or compact spacing.
sizeCTimelineSize (CTimelineSize)"md"Selects coordinated indicator and track geometry.
labelstr | NoneNoneOptionally supplies the ordered list accessible name.
class_CClassValue | None (CClassValue)NoneAdds classes to the root ordered list.
styleCStyleValue | None (CStyleValue)NoneAdds styles to the root ordered list.
attrsMapping[str, object] | NoneNoneAdds 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(...).

InputTypeDefaultEffect
stateCTimelineState (CTimelineState)"neutral"Styles authored neutral complete current pending or error status; current adds aria-current.
sideCTimelineItemSide (CTimelineItemSide)"auto"Uses the root-resolved side or overrides one Item to logical start or end.
class_CClassValue | None (CClassValue)NoneAdds classes to the rendered list item.
styleCStyleValue | None (CStyleValue)NoneAdds styles to the rendered list item.
attrsMapping[str, object] | NoneNoneAdds 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

SlotRequiredDataFallback
defaultyes{} (CTimelineDefaultSlotData)None; one or more CTimelineItem declarations are required.

CTimelineItem slots

SlotRequiredDataFallback
defaultyes{index, state, side, is_first, is_last} (CTimelineItemDefaultSlotData)None.
oppositeno{index, state, side, is_first, is_last} (CTimelineItemOppositeSlotData)Omitted.
indicatorno{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.

VariableTypePurposeDefault
--cui-timeline-gaplengthMinimum space along the sequence axis.1.5rem; compact 0.75rem
--cui-timeline-item-gaplengthSpace between the track and authored content.0.75rem; compact 0.5rem
--cui-timeline-track-sizelengthCross-axis track lane size.sm 1.5rem; md 2rem; lg 2.5rem
--cui-timeline-indicator-sizelengthIndicator inline and block size.sm 0.5rem; md 0.75rem; lg 1rem
--cui-timeline-line-widthlengthConnector and indicator border thickness.0.125rem
--cui-timeline-line-colorcolorConnector color.Adaptive neutral
--cui-timeline-indicator-colorcolorNeutral indicator color.Adaptive neutral
--cui-timeline-current-colorcolorCurrent indicator color.Adaptive blue
--cui-timeline-complete-colorcolorComplete indicator color.Adaptive green
--cui-timeline-pending-colorcolorPending indicator color.Adaptive muted neutral
--cui-timeline-error-colorcolorError indicator color.Adaptive red
--cui-timeline-muted-colorcolorOpposite 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

AttributeElementTypeMeaning
aria-labelRoot olstringOptional accessible name.
data-orientationRoot olCTimelineOrientation (CTimelineOrientation)Mirrors the track axis.
data-sideRoot olCTimelineSide (CTimelineSide)Mirrors root placement policy.
data-line-styleRoot olCTimelineLineStyle (CTimelineLineStyle)Mirrors connector treatment.
data-densityRoot olCTimelineDensity (CTimelineDensity)Mirrors spacing density.
data-sizeRoot olCTimelineSize (CTimelineSize)Mirrors geometry size.

CTimelineItem attributes

AttributeElementTypeMeaning
data-indexItem linonnegative-integer-stringExposes settled zero-based order.
data-stateItem liCTimelineState (CTimelineState)Mirrors authored visual status.
data-sideItem listart | endMirrors resolved logical placement.
data-has-oppositeItem lipresent | absentMarks an authored opposite slot.
aria-currentCurrent Item litrueIdentifies the one current event.

Selectors

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

CTimeline selectors

SelectorElementPurpose
[data-citry-ui-part="timeline"]Root olState reflections and root customization destination.
[data-citry-ui-part="item"]Item liItem attrs state and customization destination.
[data-citry-ui-part="opposite"]Optional metadata divDates and other opposite content.
[data-citry-ui-part="track"]Decorative divOwns connector segments and indicator.
[data-citry-ui-part="before"]Decorative spanConnector segment before the indicator.
[data-citry-ui-part="indicator"]Decorative spanDefault dot or custom indicator destination.
[data-citry-ui-part="after"]Decorative spanConnector segment after the indicator.
[data-citry-ui-part="content"]Content divAuthored event content destination.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CTimelineOrientationLiteral["vertical", "horizontal"]
CTimelineSideLiteral["start", "end", "alternate"]
CTimelineItemSideLiteral["auto", "start", "end"]
CTimelineLineStyleLiteral["solid", "dashed"]
CTimelineDensityLiteral["comfortable", "compact"]
CTimelineSizeLiteral["sm", "md", "lg"]
CTimelineStateLiteral["neutral", "complete", "current", "pending", "error"]
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, object] | Sequence[CStyleValue]

CTimelineDefaultSlotData

Empty dataclass: {}.

CTimelineItemDefaultSlotData

FieldTypeDefaultMeaning
indexint-Settled zero-based Item index.
stateCTimelineState (CTimelineState)-Authored Item state.
sidestart | end-Resolved logical content side.
is_firstbool-Whether this is the first Item.
is_lastbool-Whether this is the last Item.

Input type aliases

InterfaceDefinition
CTimelineItemOppositeSlotDataCTimelineItemDefaultSlotData

Input type aliases

InterfaceDefinition
CTimelineItemIndicatorSlotDataCTimelineItemDefaultSlotData

Translation keys

-