# xpl-progress-indicator A progress indicator that guides users through linear, multi-step tasks by displaying completed, current, and future steps. Progress indicators help manage user expectations by showing their position in a multi-step process, the total number of steps, and overall progress toward task completion. ## Usage ```html ``` ## Layouts ### Horizontal (Default) The horizontal layout displays steps in a row with a 16px gap between each step. Steps are connected by absolute-positioned lines that maintain consistent spacing from circle edges. Step labels appear below the circles and wrap naturally when the container narrows. This layout is ideal for page headers and top-level step navigation in desktop applications. The layout is responsive: steps distribute equally via `flex: 1`, with a minimum width of 32px (the circle size) to prevent overlap. Labels wrap within their column using `overflow-wrap: break-word`. When the container becomes too narrow for all steps, the progress indicator will overflow horizontally rather than squashing elements together. ```html ``` ### Vertical The vertical layout stacks steps vertically with connecting lines running downward. Labels appear to the right of each circle. This layout works well for side navigation panels and narrow spaces. ```html ``` ## Display Options ### Step Numbers By default, each step circle displays its index number (1, 2, 3, etc.). Set `show-numbers="false"` to display dots instead of numbers for a more minimal appearance. | Option | Visual | |--------|--------| | `show-numbers="true"` (default) | Numbered circles | | `show-numbers="false"` | Dots for waiting/active, checkmark for finished | ### Step Labels Step labels appear below (horizontal) or beside (vertical) each circle by default. Set `show-labels="false"` to hide labels and show only the step indicators. In horizontal mode, labels are constrained to the width of their step column and will wrap naturally using `overflow-wrap: break-word` when the container narrows. This prevents labels from colliding with neighboring steps. | Option | Horizontal | Vertical | |--------|------------|----------| | `show-labels="true"` (default) | Labels below circles, wrap when narrow | Labels beside circles | | `show-labels="false"` | Circles only | Circles only | ## Step States Each step can be in one of three states, determined by comparing the step index to `current-step`: | State | Visual | Description | |-------|--------|-------------| | **Waiting** | Gray circle/dot | Steps after the current step | | **Active** | Purple bordered circle | The current step (`current-step` index) | | **Finished** | Filled purple circle with checkmark | Steps before the current step | ## Icon Mapping The progress component uses `xpl-icon` for the finished step indicator: | State | Icon Name | |-------|-----------| | Finished | `check-2` | ## Design Tokens The progress component uses the following Apollo Foundation tokens: ### Horizontal Layout | Element | Property | Token/Value | |---------|----------|-------------| | Container | Min width | `0px` (fluid) | | | Width | `100%` | | | Padding horizontal | `--xpl-space-16` (16px) | | | Gap (between steps) | `--xpl-space-16` (16px) | | | Flex | `1` (equal width distribution) | | Step Circle | Width/Height | `--xpl-size-200` (32px) | | | Border | `--xpl-border-default` (waiting), `--xpl-border-focus` (active) | | | Border radius | `--xpl-border-radius-full` | | | Font size | `--xpl-font-size-title-5` | | | Font weight | `--xpl-font-weight-medium` | | Connector Line | Position | Absolute, from circle edge to edge | | | Height | `--xpl-size-0125` (2px) | | | Margins | `--xpl-space-4` (4px) from circle edges | | | Color (waiting) | `--xpl-border-default` | | | Color (finished) | `--xpl-background-action-primary-default` | | Step Label | Font size | `--xpl-font-size-title-5` | | | Color (waiting) | `--xpl-text-subdued` | | | Color (active) | `--xpl-text-default` | | | Layout | In normal flow, wraps at narrow widths | | | Max width | `100%` of step column | ### Vertical Layout | Element | Property | Token/Value | |---------|----------|-------------| | Container | Min width | `--xpl-size-0` (0px) | | | Min height | `0px` (fluid) | | | Height | `100%` | | Connector Line | Width | `--xpl-size-0125` (2px) | | | Color (waiting) | `--xpl-border-default` | | | Color (finished) | `--xpl-background-action-primary-default` | | Step Label | Margin left | `--xpl-space-8` (8px) | ### Step States | State | Circle Background | Circle Border | Circle Text | |-------|-------------------|---------------|-------------| | Waiting | Transparent | `--xpl-border-default` | `--xpl-text-subdued` | | Active | Transparent | `--xpl-border-focus` | `--xpl-text-link-default` | | Finished | `--xpl-background-action-primary-default` | `--xpl-border-accent-default` | `--xpl-text-inverse` | ## Accessibility ### ARIA structure The host element uses `role="group"` with a dynamic `aria-label` that announces the current position: | Condition | `aria-label` value | |-----------|-------------------| | Steps in progress | `"Progress: step 2 of 5"` | | All steps complete | `"Progress: all 5 steps complete"` | | No steps provided | `"Progress"` | Steps are wrapped in a container with `role="list"`, and each step is a `role="listitem"`. The active step receives `aria-current="step"`; non-active steps do not carry `aria-current`. ### Keyboard interaction This component is a display-only progress indicator and does not require keyboard interaction. It is typically used alongside form navigation controls (e.g., Previous/Next buttons) that manage step changes. ### Visual distinction - State changes use both color and shape differences (numbered circles, dots, and checkmark icons) to support colorblind users. - The `xpl-icon` component with icon `check-2` provides the finished-step checkmark at an accessible size (20px). ## HTML/CSS Usage When building the progress component in plain HTML, use the following structure: ```html
Details
2
Location
3
Review
Step 1
``` ## Properties | Property | Attribute | Description | Type | Default | | ------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- | | `currentStep` | `current-step` | Current step index. Steps with index < currentStep are "finished", the step at currentStep is "active", and steps beyond are "waiting". Set to steps.length to mark all steps as finished. Automatically clamped to [0, steps.length]. | `number` | `0` | | `layout` | `layout` | Layout direction - 'horizontal' or 'vertical' | `"horizontal" \| "vertical"` | `'horizontal'` | | `showLabels` | `show-labels` | Whether to show step labels | `boolean` | `true` | | `showNumbers` | `show-numbers` | Whether to show step numbers inside circles | `boolean` | `true` | | `steps` | -- | The steps is an array of the steps name. | `string[]` | `undefined` | ## Dependencies ### Depends on - [xpl-icon](../xpl-icon) ### Graph ```mermaid graph TD; xpl-progress-indicator --> xpl-icon style xpl-progress-indicator fill:#f9f,stroke:#333,stroke-width:4px ``` ---------------------------------------------- *Built with [StencilJS](https://stenciljs.com/)*