Component
ki-indicator
A non-interactive page-position indicator: one dot per position of a bounded sequence, exactly one highlighted as current — carousel slides, unlabeled onboarding steps, gallery pages.
<ki-indicator count="5" current="2" label="Gallery page"></ki-indicator>Examples
Section titled “Examples”Wiring to a sequence
Section titled “Wiring to a sequence”count and current (1-based) mirror the sequence the composing component
renders; the indicator itself takes no input and no focus:
<ki-indicator count="3" current="1" label="Onboarding step"></ki-indicator><ki-indicator count="3" current="3" label="Onboarding step"></ki-indicator>API reference
Section titled “API reference”When to use: show the current position within a bounded, sequential set of peer views whose navigation lives elsewhere: carousel slides, unlabeled onboarding steps, gallery pages. Wire count and current (1-based) to the sequence the consumer renders and give it a label (required authoring: assistive technology reads one graphic named "<label>, <current> / <count>"). Below two positions an indicator carries no information.
When not to use: section navigation (ki-tabs), task completion or loading (ki-progress), labeled step flows (a stepper is a separate roadmap item), interactive pagination (a future feature — the indicator takes no focus and no input; navigation belongs to the composing carousel's own controls), or conveying quantity without a current position. Position changes are never announced by the indicator itself (no live region): the composing carousel owns announcements.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
count | count | number | undefined | – | Number of positions (non-negative integer): one dot renders per position, in position order. A missing, non-numeric or negative value renders zero dots — an authoring mistake by catalog guidance, never an error state or a rendering failure (FR-002; empty ki-list precedent). |
current | current | number | undefined | – | The current position, 1-based to match the exposed position text ("2 / 5"). Exactly one dot presents the current appearance whenever count >= 1: values above count clamp to the last position, values below 1 and non-numeric values fall back to the first (FR-003). Updates re-render in place — the highlight and the exposed text follow immediately, re-applying the normalization (FR-004). |
label | label | string | undefined | – | Accessible name of the sequence ("Slide position"). The exposed name combines it with the wordless numeric position — "<label>, <current> / <count>" — on a single non-interactive graphic; without a label the name degrades to the bare position text (documented as required authoring, FR-005). The label is never rendered visually and position changes are never announced (no live region, FR-006). |
CSS parts
| Part | Description |
|---|---|
dot | Every dot: size, shape and color. |
dot-current | Additionally on the current dot: the highlight treatment. |
indicator | The row container: layout and the token-driven gap. |
CSS custom properties
The public styling contract of ki-indicator: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-indicator-dot-block-size | dimension used by the indicator component for the resting dot block size: the 8px circle diameter measured in the State=inactive vector (the 16px frame height is row alignment, carried by the current dot). |
--ki-indicator-dot-color | color used by the indicator component for the resting dot fill: Inverse_white/alpha_18, the exact variable bound to every Indicator variant fill (Black/18 light, White/18 dark) — the scheme flip rides the semantic layer. |
--ki-indicator-dot-current-block-size | dimension used by the indicator component for the current dot block size: Space/3xl, the exact variable bound as the 16px height of the State=active pill (the full row line; declared family extension, design-extraction §Decisiones). |
--ki-indicator-dot-current-color | color used by the indicator component for the current dot treatment: Inverse_white/alpha_18, the exact fill of the State=active ring vector (Black/18 light, White/18 dark) — painted as the pill ring in onmars, as the solid dot in themes that zero the hole. |
--ki-indicator-dot-current-hole-block-size | dimension used by the indicator component for the block size of the transparent hole cut from the current pill: the 6px cutout height measured in the State=active vector; the ring width derives by construction as (current block size − hole block size) / 2 and a theme resolves it to zero for a solid dot (declared family extension, design-extraction §Decisiones). |
--ki-indicator-dot-current-inline-size | dimension used by the indicator component for the current dot inline size: Space/10xl, the exact variable bound as the 32px width of the State=active pill — the MarsUI elongation lives here, never in an attribute (FR-007). |
--ki-indicator-dot-current-radius | dimension used by the indicator component for the current dot shape: Radius/radius_round bound in Figma — the pill is a radius token, never an attribute (002 shape precedent). |
--ki-indicator-dot-inline-size | dimension used by the indicator component for the resting dot inline size: Space/md, the exact variable bound as the 8px width of the State=inactive symbol; the painted circle is 8x8 centered in the 16px row line. |
--ki-indicator-dot-radius | dimension used by the indicator component for the resting dot shape: Radius/radius_round bound in Figma — the round dot is a radius token, never an attribute (002 shape precedent). |
--ki-indicator-gap | dimension used by the indicator component for the space between dots: Space/sm, the exact variable bound as the 6px gap of the composed Nav_indicator row (node 14195:5866, specs/024-ki-indicator/design-extraction.md). |
--ki-indicator-motion-duration | duration used by the indicator component for the highlight transfer between dots: the Figma set documents no motion, so onmars resolves the single transition to the fast semantic duration (FR-008; disabled under reduced motion by construction). |
--ki-indicator-motion-easing | easing used by the indicator component for the highlight-transfer transition (MarsUI standard curve; previously the UA default ease applied). |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-standard-decelerate | Utility entrance curve. M3 md.sys.motion.easing.standard-decelerate. onmars: the MarsUI decelerate curve (ki.easing.out). |
--ki-typography-family-body | semantic font family for typography family body. |
Accessibility
Section titled “Accessibility”label is required authoring: assistive technology reads one graphic named
“<label>, <current> / <count>”. Position changes are never
announced by the indicator itself (no live region) — the composing carousel
owns announcements and navigation. For section navigation use
ki-tabs; for task completion use
ki-progress.