Skip to main content

CnTimelineStages

Visualizes sequential progression through named stages. Stages are automatically classified as completed (before current), current, or upcoming (after current). Supports horizontal and vertical orientations, small/medium sizes, clickable stages with keyboard navigation (roving tabindex), and ARIA roles.

Try it​

Loading CnTimelineStages playground…

Usage​

<!-- Basic horizontal timeline -->
<CnTimelineStages
:stages="[
{ id: 'new', label: 'New' },
{ id: 'review', label: 'In Review', subtitle: 'Since Mar 15' },
{ id: 'approved', label: 'Approved' },
{ id: 'done', label: 'Done' },
]"
current-stage="review" />

<!-- Vertical, clickable — for pipeline stage selection -->
<CnTimelineStages
:stages="pipelineStages"
:current-stage="deal.stage"
orientation="vertical"
:clickable="true"
@stage-click="onStageClick" />

<!-- Small size, custom indicator via slot -->
<CnTimelineStages :stages="stages" current-stage="active" size="small">
<template #indicator="{ stage, state }">
<span :class="['my-dot', `my-dot--${state}`]" />
</template>
</CnTimelineStages>
function onStageClick({ stage, index }) {
updateDealStage(stage.id)
}

Props​

PropTypeRequiredDefaultDescription
stagesArray✓—Stage objects: { id, label, subtitle?, disabled?, blocked?, hint? }. id must be unique; subtitle is optional secondary text. See a stage that cannot be chosen for the last three
currentStageString | Numbernullid of the active stage. Stages before it are completed, stages after are upcoming. null = all upcoming
orientationString'horizontal'Layout direction: 'horizontal' or 'vertical'
sizeString'medium'Indicator size: 'medium' (32px) or 'small' (20px)
clickableBooleanfalseWhether stages emit stage-click and support arrow-key navigation
ariaLabelString'Progress stages'Accessible label for the timeline container

Events​

EventPayloadDescription
stage-click{ stage, index }Emitted when a clickable stage is activated via click, Enter, or Space
stage-blocked{ stage, index }Emitted instead of stage-click when the activated stage is disabled. Answer it, or a click on a refused stage does nothing and says nothing

Slots​

SlotScopeDescription
indicator{ stage, index, state }Custom indicator element replacing the default checkmark/dot
label{ stage, index, state }Custom label block replacing the default label + subtitle

Stage states​

StateCondition
'completed'Stage index < current stage index
'current'Stage matches currentStage
'upcoming'Stage index > current stage index

A stage that cannot be chosen​

Three keys on a stage object, and they answer three different questions.

KeyWhat it saysWhat the person sees
disabledThis stage cannot be chosenDimmed, a dashed indicator, a not-allowed cursor. It keeps its focus stop, carries aria-disabled="true" and emits stage-blocked instead of stage-click
blockedA guard refused it for this recordFull contrast, the warning colour, an exclamation mark in the indicator. Still refused, still emits stage-blocked
hintWhyThe stage's title, so a mouse-over reveals it
<CnTimelineStages
:stages="[
{ id: 'intake', label: 'Ontvangen' },
{ id: 'work', label: 'In behandeling' },
{
id: 'done',
label: 'Afgehandeld',
disabled: true,
blocked: true,
hint: 'Vereist veld ontbreekt: description',
},
]"
current-stage="work"
orientation="vertical"
:clickable="true"
@stage-blocked="say($event.stage.hint)" />

Set blocked only on the stages a guard actually refused. A stage further down the process is not a refusal, and if every stage is orange then none of them reads as refused. The stage the record is on never takes the colour, whatever you pass: a refusal on the place the record already sits says no to a move nobody is making.

hint is one route to the reason, not the only one. A tooltip reaches neither a touch screen nor a keyboard, so answer stage-blocked as well. CnStagesWidget does both: it shows the sentence in a warning note card under the strip, and it keeps a copy inside the stage for a screen reader.

Vertical stages are top aligned. A stage carrying a long reason is taller than its neighbours, and centring it slid that one label out of line with the others. The connector line runs from each circle's centre to the next one down, which is a fixed distance from the top of each row, so the line stays on the circles whatever a row contains.

Reference (auto-generated)​

The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnTimelineStages.vue and update automatically whenever the component changes.

OpenRegister reliance​

none: this component does not touch OpenRegister, directly or through anything it imports. 0 direct references, 0 files reached through imports.

See the reliance overview for the filterable list.

Props​

NameTypeRequiredDefaultDescription
stages{ id: string, label: string, subtitle?: string, disabled?: boolean, blocked?: boolean, hint?: string }[]✓—Array of stage objects. Each must have id (unique) and label (display text). Optional subtitle for secondary text below the label. Optional disabled marks a stage that cannot be chosen: in clickable mode it keeps its focus stop, carries aria-disabled="true" and emits stage-blocked instead of stage-click, so the consumer can tell the person why nothing happened. Optional blocked says WHY it cannot be chosen: a guard refused this record, rather than the stage merely sitting further down the process. Those are different claims and they must not look alike, so a blocked stage keeps full contrast and takes the warning colour and an exclamation mark, where a merely-upcoming one stays dimmed. Set it on the stages a guard actually refused: if every stage is orange, none of them reads as refused. Optional hint is the explanation, put on the stage's title so a mouse-over reveals it. It is the pointer route to a reason that is not printed on screen; it is not the only route, because a tooltip reaches neither touch nor keyboard.
currentStageunionnullThe id of the currently active stage. Stages before it are "completed", stages after it are "upcoming". If null/undefined or not matching any id, all stages are "upcoming".
orientationstring'horizontal'Layout orientation: "horizontal" (left-to-right) or "vertical" (top-to-bottom).
sizestring'medium'Size variant: "medium" (32px indicators) or "small" (20px indicators).
clickablebooleanfalseWhether stages are clickable. When true, stages emit stage-click on click/Enter/Space and support keyboard navigation with arrow keys.
ariaLabelstring() =&gt; t('nextcloud-vue', 'Progress stages')Accessible label for the timeline container.

Events​

NamePayloadDescription
stage-click—Emitted when a clickable stage is activated (click, Enter, or Space).
stage-blocked—Emitted when a stage that cannot be chosen is activated. The stage still emits no stage-click, so nothing acts on it. This says the person TRIED, which is what lets a consumer answer them. Without it a blocked stage was silent to anyone not running a screen reader: no message, no move, nothing.

Slots​

NameBindingsDescription
indicatorstage, index, state
labelstage, index, state