# Timeline

The Timeline component visually represents a sequence of events or stages in a linear, chronological order. Designed with clarity and accessibility in mind, it helps users understand the progress, status, and associated actions within a workflow.

<figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2F69egHTEIVqM9aAdN1Klm%2Fimage.png?alt=media&#x26;token=48fc7f63-dd0e-44a3-817c-a69bf4990629" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Component React" %}

```
// Sample code

<Timeline
      label="Upcoming Timeline Step3"
      subElements={subElements}
      variant="upcoming"
      showConnector={true}
    />
```

{% endtab %}

{% tab title="Component Flutter" %}

```
// Sample code

DigitTimeline(
          currentStep: TimelineStepState.present,
          label: 'Ongoing state',
          description: const ['18 / 02 / 2023'],
          additionalWidgets: [
                TimelineFileWidget(
                  file: TimelineFiles(
                    url: 'https://example.com/sample.pdf',
                    name: 'Document',
                    fileType: 'pdf',
                  ),
                  openFile: true,
                ),
                TimelineFileWidget(
                  file: TimelineFiles(
                    url: 'https://static.remove.bg/sample-gallery/graphics/bird-thumbnail.jpg',
                    name: 'Image',
                    fileType: 'jpg',
                  ),
                  openFile: true,
                )
          ],
        );
```

{% endtab %}

{% tab title="Component Design" %}

{% endtab %}
{% endtabs %}

## Anatomy

<figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2Fo2rQ6fzXRbA23zeMopdC%2Fimage.png?alt=media&#x26;token=d30f33ce-8e97-4bfa-a8e7-8dedfabd34f3" alt=""><figcaption></figcaption></figure>

***

## Variants

***

<table data-header-hidden><thead><tr><th width="321"></th><th></th></tr></thead><tbody><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FuuF6ytgunFg7hEgqtkTr%2Fimage.png?alt=media&#x26;token=1d0b4dc9-e4f1-42ba-a43b-2ee268ca1b60" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>Upcoming</strong></p><p>Displays future events or steps in the process. The visual indicator is muted to reflect inactivity, and it can include relevant date/time info.</p></td></tr><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FaRXv31Nhj5U87MX51Vxn%2Fimage.png?alt=media&#x26;token=52426b0a-e8eb-45f0-85b6-c03ea716d249" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>In Progress</strong></p><p>Represents tasks or stages currently underway. It uses an active visual indicator to denote ongoing status and may include interactive elements like “View Details”.</p></td></tr><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FlUBwQSM2BzlGOpK37s1L%2Fimage.png?alt=media&#x26;token=da2b4adc-2f09-4a9b-a20d-6ad74b29e6ea" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>Completed</strong></p><p>Marks finished tasks using a filled, completed icon. This variant reinforces a sense of progression and task completion.</p></td></tr></tbody></table>

***

## Properties

|                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p><strong>Default</strong></p><p>Shows only the stage name without additional data, keeping the interface clean.</p>                                                                        | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2F7D5CjRaXygejq5a1l3s1%2Fimage.png?alt=media&#x26;token=35f12ed4-8f88-4427-aee9-22d36b3d149c" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Date</strong></p><p>Includes the date beneath the stage to inform users of timing for events or steps.</p>                                                                        | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FoSk5aFqatNE7vz28cE75%2Fimage.png?alt=media&#x26;token=ebf90b49-e7a8-4cc1-a0b8-687ccb1d53b3" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Additional Elements</strong></p><p>Enhances the component with date/time details and a collapsible “View Details” element, which opens further content.</p>                       | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FHCnVDp6fwzR4VokRJADw%2Fimage.png?alt=media&#x26;token=36cab7cf-a40d-49a2-a212-d4c9968d8872" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Expanded</strong></p><p>Displays rich content such as text blocks, image/document previews, and action buttons to support user interaction.</p>                                   | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FR1LuQcCT7sCvUXvmwQ6j%2Fimage.png?alt=media&#x26;token=8ea2415f-c0e7-4f84-8f51-dfa0a1a10d06" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Error Timeline</strong></p><p>Highlights failed or incomplete steps with red indicators and messaging like “Failed”, drawing attention to issues that require user attention.</p> | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2Fz82ksMBNQTWHJkmEhrOO%2Fimage.png?alt=media&#x26;token=680f1420-625f-4dc9-a2ff-fa3b15398994" alt=""><figcaption></figcaption></figure></div> |

## Property Configuration Table

Each design component offers a range of configurable options. These options are intentionally platform-agnostic, allowing implementations to adapt and tailor them to align with the specific requirements of the chosen framework.

{% tabs %}
{% tab title="React" %}

<table><thead><tr><th width="257">Property</th><th>Value</th><th>Default</th></tr></thead><tbody><tr><td>label</td><td>text</td><td></td></tr><tr><td>subElements</td><td>text</td><td></td></tr><tr><td>variant</td><td>yes/no</td><td>no</td></tr><tr><td>viewDetailsLabel</td><td>yes/no</td><td>no</td></tr><tr><td>hideDetailsLabel</td><td>number</td><td></td></tr><tr><td>additionalElements</td><td>yes/no</td><td></td></tr><tr><td>inline</td><td>yes/no</td><td>no</td></tr><tr><td>individualElementStyles</td><td>yes/no</td><td>no</td></tr><tr><td>showConnector</td><td>yes/no</td><td>no</td></tr><tr><td>className</td><td>number</td><td>no</td></tr><tr><td>isLabelFirst</td><td>yes/no</td><td>no</td></tr><tr><td>isNextActiveStep</td><td>text</td><td>no</td></tr><tr><td>showDefaultValueForDate</td><td>yes/no</td><td>no</td></tr><tr><td>isError</td><td>yes/no</td><td></td></tr><tr><td>initialVisibleAdditionalElementsCount</td><td>yes/no</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Flutter" %}

<table><thead><tr><th>Property</th><th width="209">Value</th><th>Default</th></tr></thead><tbody><tr><td>label</td><td>String</td><td>required</td></tr><tr><td>description</td><td>List&#x3C;String></td><td>-</td></tr><tr><td>currentStep</td><td>TimelineStepState</td><td>required</td></tr><tr><td>additionalWidgets</td><td>List&#x3C;Widget></td><td>-</td></tr><tr><td>additionalHideWidgets</td><td>List&#x3C;Widget></td><td>-</td></tr><tr><td>viewDetailText</td><td>String</td><td>-</td></tr><tr><td>hideDetailText</td><td>String</td><td>-</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

## Behaviours

|                                                                                                                                                                                                                                                                                            |                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2F4kx4ZbIQc3yEQ27z4Pu8%2Fimage.png?alt=media&#x26;token=7e4e9a7d-39e8-43ac-864a-8b5a86e89fce" alt=""><figcaption></figcaption></figure></div> | <p><strong>Progressive Expansion</strong></p><p>Sections expand to reveal additional information, files, and actions only when the user chooses to explore, preventing visual clutter.</p> |

***

## Usage Guide

***

| <p><strong>Ensure Clear Status Representation</strong></p><p>Each timeline status should be visually distinct using clear colours, icons, and typography so that users can easily understand the progression and current state.</p><p></p><p>Icons should clearly match their status. Avoid using similar icons for different statuses, which can lead to misinterpretation.</p> | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FrGVknjnoGPx0xY34owah%2Fimage.png?alt=media&#x26;token=1bce4102-6570-46a1-b607-d939e9d2af88" alt=""><figcaption></figcaption></figure></div> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                                                                                                                                                                                                                                                                                                                                                                                  | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FivJicotGvI3sSlljCdjj%2Fimage.png?alt=media&#x26;token=4d1e2799-051d-41f6-912d-564e1e2224fe" alt=""><figcaption></figcaption></figure></div> |

## Changelog

***

| Date         | Number  | Notes                                                                                           |
| ------------ | ------- | ----------------------------------------------------------------------------------------------- |
| Dec 15, 2024 | v-0.0.2 | <p>This component is added to the website.<br>This component is now individually versioned.</p> |

## Design Checklist

***

<table data-header-hidden><thead><tr><th width="129" data-type="checkbox"></th><th></th></tr></thead><tbody><tr><td>true</td><td><strong>All interactive states</strong> - Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).</td></tr><tr><td>true</td><td><strong>Accessible use of colours</strong> - Colour is not used as the only visual means of conveying information (WCAG 2.1 1.4.1)</td></tr><tr><td>true</td><td><strong>Accessible contrast for text</strong> - Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).</td></tr><tr><td>true</td><td><strong>Accessible contrast for UI components</strong> - Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).</td></tr><tr><td>true</td><td><strong>Keyboard interactions</strong> - Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).</td></tr><tr><td>false</td><td><strong>Screen reader accessible</strong> - All content, including headings, labels, and descriptions, is meaningful, concise, contextual and accessible by screen readers.</td></tr><tr><td>true</td><td><strong>Responsive for all breakpoints</strong> - Responsiveness for 3 breakpoints - Mobile, Tablet and Desktop</td></tr><tr><td>true</td><td><strong>Usage guidelines</strong> - Includes a list of dos and don'ts that highlight best practices and common mistakes.</td></tr><tr><td>false</td><td><strong>Writing guidelines</strong> - Content standards and usage guidelines for writing and formatting in-product content for the component.</td></tr><tr><td>true</td><td><strong>Defined variants and properties</strong> - Includes relevant variants and properties (style, size, orientation, optional iconography, decorative elements, selection states, error states, etc.)</td></tr><tr><td>true</td><td><strong>Defined behaviours</strong> - Guidelines for keyboard navigation and focus, layout management (including wrapping, truncation, and overflow), animations, and user interactions.</td></tr><tr><td>true</td><td><strong>Design Kit</strong> - Access to the design file for the component in Figma, multiple options, states, colour themes, and platform scales.</td></tr></tbody></table>