# Button

<ThemedImage light={button} dark={buttonDark} alt="" />

## Overview

Buttons should be used to trigger an action by guiding users to achieve the desired actions of a page. Depending on the need and the context, several buttons types and variants are available to help you build meaningful interfaces and prevent mistakes.

**Note:** Buttons should never be used for an alternative purpose to what it was initially intended for. Avoid using buttons for navigational purposes (menus, tabs, etc.) or clickable elements within sentences. Instead, please refer to the dedicated component available in the TDS.

### Usage

When to use:

- To offer a default action as well as the possibility of choosing a different action by selecting from a set of alternatives.
- In complex applications, to not visually overwhelm users with too much cognitive load.
- For repeat-use interfaces with a large number of commands that need to be consolidated.

When not to use:

- If default action and alternatives don’t have a strong relationship.
- Proposing too much alternatives and struggling with choice paralysis.
- Using split buttons for navigation menus on websites.

### Sources

- [Split Buttons: Definition](https://www.nngroup.com/articles/split-buttons/#:~:text=Definition%3A%20A%20split%20button%20is,list%20of%20other%20possible%20actions) by Nielsen Norman Group
- [Split Buttons: Documentation](https://developers.arcgis.com/calcite-design-system/components/split-button/) by ArcGIS Developer

## Anatomy

<ThemedImage light={buttonAnatomy} dark={buttonAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Button

| Property           | Values                                                 | Default           |
| ------------------ | ------------------------------------------------------ | ----------------- |
| **size**           | small / medium / large / xlarge                        | medium            |
| **color**          | primary / success / warning / danger / neutral / white | primary           |
| **\*state**        | default / hover / focused / pressed / loading          | default           |
| **disabled**       | false / true                                           | false             |
| **\*manualSize**   | false / true                                           | false             |
| **label**          | text                                                   | "Download"        |
| **\*hasLeftIcon**  | boolean                                                | true              |
| **leftIcon**       | instance swap                                          | arrow_circle_down |
| **\*hasRightIcon** | boolean                                                | true              |
| **rightIcon**      | instance swap                                          | arrow_forward     |

#### ❖ Component: Icon Button

| Property     | Values                                        | Default         |
| ------------ | --------------------------------------------- | --------------- |
| **size**     | small / medium / large / xlarge               | medium          |
| **\*state**  | default / hover / focused / pressed / loading | default         |
| **disabled** | false / true                                  | false           |
| **icon**     | instance swap                                 | swap_horizontal |

## Behaviour

### Sizes

Buttons support four sizes:

- Small (S) for very small layouts
- Medium (M) as default for desktop devices
- Large (L) as default for tablet and mobile devices
- Extra large (XL) for emphasized actions

These buttons have been specially designed with accessibility in-mind, backed by industry standard practices from [Google’s Material Design](https://m2.material.io/design/usability/accessibility.html#layout-and-typography) and [Apple’s Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility).

<ThemedImage
  light={buttonBehaviourSizes}
  dark={buttonBehaviourSizesDark}
  alt=""
/>

### Variants

**Primary buttons** are the main call to action on any page.
It is advised that a primary button is only used once on a single page. This avoids drawing the user’s attention away from the primary action you intended for the page.

**Outline buttons** are for secondary call to actions on any page. Often the secondary button is the alternative we give users to the primary action.
Multiple secondary buttons can be used on a single page, however it is advised that you ensure the content of your page is balanced. Too many calls to action can make it hard for users to know what to do next.

**Ghost buttons** are for miscellaneous actions on any page.
Multiple tertiary buttons can be used on a single page, however it is advised that you ensure the content of your page is balanced. Too many calls to action can make it hard for users to know what to do next.

<ThemedImage
  light={buttonBehaviourVariants}
  dark={buttonBehaviourVariantsDark}
  alt=""
/>

### Severity

**Primary** buttons represent the main action or primary call to action on a page. It should be used sparingly to draw attention to important actions.

**Success** buttons represent successful actions or completion of a task. This could include actions that result in a successful operation or confirmation message.

**Warning** buttons represent potentially harmful or irreversible actions. This could include actions that delete data or cancel a process, or that require additional caution and confirmation.

**Danger** buttons represent potential issues or warnings. This could include actions that require additional confirmation or that might result in data loss or other negative consequences.

<ThemedImage
  light={buttonBehaviourSeverity}
  dark={buttonBehaviourSeverityDark}
  alt=""
/>

### Left & Right icons

**Usage of Left or Right icons depends on the context, the usage and the goal of the button.**

**Left icons** feel visually anchored and more consistent with the left-alignment of the text. Moreover, it’s the more common pattern among other applications, and being consistent is a positive behavior for users - Jakob’s Law. Last but not least, large menu width do not impact the comprehension of the button and the left of the button can be used for counters.

**Right icons** can be used to keep text from different button aligns. It also adds a rightward movement because text demands more cognitive load than icons. A consideration is that it can visually trapped space, between the icons and the menu title spaces, and create unpleasant reading.

<ThemedImage
  light={buttonBehaviourLeftRightIcons}
  dark={buttonBehaviourLeftRightIconsDark}
  alt=""
/>

### Auto layout & manual resize

By default, the button has an automatic horizontal sizing based on its content. It will grow depending on the length of the label inside of it.

To manually adjust the size, for full width buttons for example, you need to apply a “Fill container” sizing setting to the “Base Button” layer

<ThemedImage
  light={buttonBehaviourAutoLayoutManualResize}
  dark={buttonBehaviourAutoLayoutManualResizeDark}
  alt=""
/>

## Usage Guidelines

### Labelling

Buttons labels describe the action that will occur when the user uses it. It is important to choose the right words to make the action clear for the user, and facilitate its decisions. Using the wrong words on button labels can create confusion, more work, and slower task times for the users.

#### Prefer action verbs than generic terms

Words should describe the action or result of pressing/clicking the button. According to some studies, (e.g. [Paradox of the Active User](https://www.nngroup.com/articles/paradox-of-the-active-user/)) most people avoid reading whenever it is possible. That is is why naming a button with “Ok” or “Yes/No” won’t help them in any way. Instead, use action verbs to encourage users to take action without necessarily read the dialog.

<ThemedImage
  light={buttonUsageGuidelinesLabellingPreferActionVerbsThanGenericTerms}
  dark={buttonUsageGuidelinesLabellingPreferActionVerbsThanGenericTermsDark}
  alt=""
/>

#### Choose precise and specific words

Each action verb can have a specific connotation. Using imprecise diction can make users misinterpret the button.
Moreover, a vague and generic label can cause uncertainty in users, who won’t be sure of the result of their actions.

<ThemedImage
  light={buttonUsageGuidelinesLabellingChoosePreciseAndSpecificWords}
  dark={buttonUsageGuidelinesLabellingChoosePreciseAndSpecificWordsDark}
  alt=""
/>

- For example, “delete” and “remove” are similar in meaning, but can have a different connotation. “Delete” implies that the button will erase something from the system while “remove” implies that the button will separate something from a group. Using these words in the wrong context can cause users concern when they want to press the button.
- “Submit” can be used for many contexts and make the action vague and unclear. In contrast the word “publish” is specific to online publishing, so users will be sure that their post will be posted after they press the button.

#### Text format

Capitalization style of the button affects the emotional reaction and can either engage or repel them.
[TDS Foundations](/docs/foundations/typography#formatting) recommends that all buttons use **sentence case**. Sentence cases make the button easier to read, and natural.

In contrast, title-style capitalization has a more impersonal tone, while all-uppercase style decrease readability and conveys a loud and strict tone. Finally, all-lower case style conveys a casual and lazy tone, with a lack of professionalism and trust.

<ThemedImage
  light={buttonUsageGuidelinesLabellingTextFormat}
  dark={buttonUsageGuidelinesLabellingTextFormatDark}
  alt=""
/>

### Icons

Icons in buttons can make information easier to find and scan. We recommend to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button. However, right icon can be set for right-to-left reading usages.

<ThemedImage
  light={buttonUsageGuidelinesIcons0}
  dark={buttonUsageGuidelinesIcons0Dark}
  alt=""
/>

An exception to this is **directional call to actions**, where it is more appropriate to place the icon in the correct direction of travel for the user on the page (e.g. in order for a user to progress to the next step, in a left-to-right country, they will anticipate an arrow pointing right on the right-hand side of the button).

<ThemedImage
  light={buttonUsageGuidelinesIcons1}
  dark={buttonUsageGuidelinesIcons1Dark}
  alt=""
/>

### Icon buttons

Icon buttons are buttons without visible text labels by default. They are used to perform a quick action on an object (e.g. add, delete, add an item, send…) or trigger a new element to appear on the page (e.g. open a modal, reveal a menu…)

Since icon buttons don’t display an explicit labelling, it is important to use a clear visual representation of the action it will trigger.

<ThemedImage
  light={buttonUsageGuidelinesIconButtons}
  dark={buttonUsageGuidelinesIconButtonsDark}
  alt=""
/>

#### Use the 5-second rule

Icons should always communicate meaning. Don’t overuse them or use them for decoration.

When you are trying to come up with your design for icon, consider adopting the **five-second rule**. “If you take more than 5 seconds to come up with that object that will represent that idea or concept, then it is less likely that your users can see that design and associate it with that object.”

#### Icon Usability

[Find more informations about Icon Usability and how to use it effectively to help the users understand the meaning and reduce ambiguity.](https://www.nngroup.com/articles/icon-usability/)

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284249&t=244StnnCdoCtO9oW-4)



# Split Button

<ThemedImage light={splitButton} dark={splitButtonDark} alt="" />

## Overview

Split Buttons are dual-function menu buttons with two components: a label and an arrow; clicking on the label selects a default action, and clicking on the arrow opens up a list of other possible actions: the alternatives.

### Usage

When to use:

- To offer a default action as well as the possibility of choosing a different action by selecting from a set of alternatives.
- In complex applications, to not visually overwhelm users with too much cognitive load.
- For repeat-use interfaces with a large number of commands that need to be consolidated.

When not to use:

- If default action and alternatives don’t have a strong relationship.
- Proposing too much alternatives and struggling with choice paralysis.
- Using split buttons for navigation menus on websites.

### Sources

- [Split Buttons: Definition](https://www.nngroup.com/articles/split-buttons/#:~:text=Definition%3A%20A%20split%20button%20is,list%20of%20other%20possible%20actions) by Nielsen Norman Group
- [Split Buttons: Documentation](https://developers.arcgis.com/calcite-design-system/components/split-button/) by ArcGIS Developer

## Anatomy

<ThemedImage light={splitButtonAnatomy} dark={splitButtonAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Component: Split Button

| Property      | Values                                                                                | Default |
| ------------- | ------------------------------------------------------------------------------------- | ------- |
| **size**      | small / medium / large                                                                | medium  |
| **\*hasIcon** | false / true                                                                          | true    |
| **visible**   | false / true                                                                          | false   |
| **placement** | none / bottom-left / bottom-center / bottom-right / top-left / top-center / top-right | none    |

#### ❖ Sub-component: [Dropdown Menu Item](/docs/components/dropdown-menu)

#### ❖ Sub-component: [Button](/docs/components/button)

## Behaviour

### Sizes

Split buttons exist with 3 different sizes: small, medium and large.

<ThemedImage
  light={splitButtonBehaviourSizes}
  dark={splitButtonBehaviourSizesDark}
  alt=""
/>

### Icons

Icons can be used in split buttons items, and should be used as often as possible to add clarity and context.

Icons in split buttons can make information easier to find and scan. The only option is to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button.

<ThemedImage
  light={splitButtonBehaviourIcons}
  dark={splitButtonBehaviourIconsDark}
  alt=""
/>

### Menu (dropdown)

By default, split button doesn’t have an open menu to show alternatives.

Alternatively, the open state can be used to show alternatives or to animate prototypes.

<ThemedImage
  light={splitButtonBehaviourMenuDropdown}
  dark={splitButtonBehaviourMenuDropdownDark}
  alt=""
/>

### Menu position

By default, split button’s menu is closed. The open state allows the user to choose the menu’s position to fit perfectly with their unique context.

As the menu is a dropdown component, it offers all the possible customizations with this element.

<ThemedImage
  light={splitButtonBehaviourMenuPosition}
  dark={splitButtonBehaviourMenuPositionDark}
  alt=""
/>

### Color variations

#### Ghost split button

<ThemedImage
  light={splitButtonBehaviourColorVariationsGhostSplitButton}
  dark={splitButtonBehaviourColorVariationsGhostSplitButtonDark}
  alt=""
/>

#### Ghost Neutral split button

<ThemedImage
  light={splitButtonBehaviourColorVariationsGhostNeutralSplitButton}
  dark={splitButtonBehaviourColorVariationsGhostNeutralSplitButtonDark}
  alt=""
/>

## Usage Guidelines

### Use split buttons to combine relevant button actions

- **Don’t:** use multiple primary actions at the same place
- **Do:** combine them in a split button when relevant

<ThemedImage
  light={
    splitButtonUsageGuidelinesUseSplitButtonsToCombineRelevantButtonActions
  }
  dark={
    splitButtonUsageGuidelinesUseSplitButtonsToCombineRelevantButtonActionsDark
  }
  alt=""
/>

### Use split buttons not as a group

- **Don’t:** use split buttons if the intention is to use it as a group
- **Do:** use them if the intention is to use it as a single element

<ThemedImage
  light={splitButtonUsageGuidelinesUseSplitButtonsNotAsAGroup}
  dark={splitButtonUsageGuidelinesUseSplitButtonsNotAsAGroupDark}
  alt=""
/>

### Propose related alternatives

- **Don’t:** use split button for proposing unrelated alternatives
- **Do:** choose wisely the alternatives to avoid cognitive overload

<ThemedImage
  light={splitButtonUsageGuidelinesProposeRelatedAlternatives}
  dark={splitButtonUsageGuidelinesProposeRelatedAlternativesDark}
  alt=""
/>

### The lesser the better

- **Don’t:** use split button for proposing a huge amount of alternatives
- **Do:** choose wisely the alternatives to avoid cognitive overload and impact on the time to make a choice - Hick's law

<ThemedImage
  light={splitButtonUsageGuidelinesTheLesserTheBetter}
  dark={splitButtonUsageGuidelinesTheLesserTheBetterDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284241&t=244StnnCdoCtO9oW-4)



# Floating Button

<ThemedImage light={floatingButton} dark={floatingButtonDark} alt="" />

## Overview

A Floating Action Button (FAB) emphasizes the main action of the page. It is an action button placed in the foreground of the interface. It can also be used in specific situations such as map navigation or multi edition.

You can refer to our documentation about [Shadows & Elevation](/docs/foundations/shadows-elevation) to understand how to embed it well in your interfaces.

### Usage

When to use:

- To simplify access to the main action of the page
- To provide a panel of common actions of several items
- To keep a fixed action despite a scroll

When not to use:

- As a secondary action: if there are already some actions in the interface
- By putting several FABs on the same interface

### Sources

[Floating Action Button](https://m3.material.io/components/floating-action-button/overview) by Material Design.

## Anatomy

<ThemedImage
  light={floatingButtonAnatomy}
  dark={floatingButtonAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ FAB - Button Filled / Outline / Flat

| Property           | Values                                         | Default    |
| ------------------ | ---------------------------------------------- | ---------- |
| **size**           | small / medium / large / xlarge                | medium     |
| **color**          | primary / success / warning / danger / neutral | primary    |
| **\*state**        | default / hover / focused / pressed            | default    |
| **disabled**       | false / true                                   | false      |
| **label**          | text                                           | Download   |
| **\*hasLeftIcon**  | boolean                                        | true       |
| **leftIcon**       | instance swap                                  | swap_horiz |
| **\*hasRightIcon** | boolean                                        | false      |
| **rightIcon**      | instance swap                                  | swap_horiz |

#### ❖ FAB - Icon button Filled / Outline / Flat

| Property            | Values                                         | Default    |
| ------------------- | ---------------------------------------------- | ---------- |
| **size**            | small / medium / large / xlarge                | medium     |
| **color**           | primary / success / warning / danger / neutral | primary    |
| **\*state**         | default / hover / focused / pressed            | default    |
| **disabled**        | false / true                                   | false      |
| **leftAnnotation**  | boolean                                        | false      |
| **rightAnnotation** | boolean                                        | false      |
| **icon**            | instance swap                                  | swap_horiz |

#### ❖ FAB - Icon buttons stack Primary / Neutral

| Property            | Values                 | Default |
| ------------------- | ---------------------- | ------- |
| **color**           | primary / neutral      | primary |
| **size**            | small / medium / large | medium  |
| **items**           | 2 / 3 / 4 / 5 / 6 / 7  | 7       |
| **showAnnotations** | false / true           | false   |
| **textPosition**    | none / left / right    | none    |
| **isOpen**          | boolean                | false   |

## Behaviour

### Sizes

FAB supports four sizes:

- Small (S) for very small layouts
- Medium (M) as default for desktop devices
- Large (L) as default for tablet and smartphone devices

Note: we recommend to avoid to use individually the XSmall size because it is designed for the Icon Buttons Stack as a sub-item.

<ThemedImage
  light={floatingButtonBehaviourSizes}
  dark={floatingButtonBehaviourSizesDark}
  alt=""
/>

### Style variations

The Floating Action Button is available in 3 styles: Filled, Outlined and Flat.

**Filled** style is appropriate to emphasize one main action or open the sub-actions stack. It will pop on your screen if your interface is mainly light-themed. If it is not the case we recommend to use the **Outlined** version which will be more visible in colourful screens.

Eventually you can use the **Flat** one as a sub-action when an overlay is active. We do not recommend this use as a main action due to the lack of contrast in that case.

<ThemedImage
  light={floatingButtonBehaviourStyleVariations}
  dark={floatingButtonBehaviourStyleVariationsDark}
  alt=""
/>

### Severity

**Primary** FAB buttons represent the main action or primary call to action on a page. It should be used sparingly to draw attention to important actions.

**Success** FAB buttons represent successful actions or completion of a task. This could include actions that result in a successful operation or confirmation message.

**Warning** FAB buttons represent potentially harmful or irreversible actions. This could include actions that delete data or cancel a process, or that require additional caution and confirmation.

**Danger** FAB buttons represent potential issues or warnings. This could include actions that require additional confirmation or that might result in data loss or other negative consequences.

Use **Neutral** FAB for action that doesn’t need to grab too much user attention.

<ThemedImage
  light={floatingButtonBehaviourSeverity}
  dark={floatingButtonBehaviourSeverityDark}
  alt=""
/>

### FAB Types

**We provide you three types of Floating Action Button:**

**FAB - Icon Button** which is the well-know FAB. We advise to use it in small interfaces such as Smartphone or Tablet app for an individual usage. In the case of applications with a full screen display, this FAB can also be used to provide different interactions to the users (i.e. mapping tool)

**FAB - Button**: more explicit, it allows the same uses as the FAB - Icon Button with a textual description. Be careful to ensure that the label is not too long in restricted interfaces.

**FAB - Sub-Actions Drawer** has a particular use because it allows to display several actions at the trigger of the main button. This stack gather actions consistently with the context and hideable by triggering once again the main button. Furthermore, we advise you to add an overlay behind your FAB to put the light on these sub-actions.

<ThemedImage
  light={floatingButtonBehaviourFabTypes}
  dark={floatingButtonBehaviourFabTypesDark}
  alt=""
/>

### FAB Icon: Annotation

You can **display additional text** to your FAB - Icon Button in case you want to add context to your action.

We recommend hover usage for a FAB - Icon Button and permanent display for a FAB - Sub-Actions Drawer.

<ThemedImage
  light={floatingButtonBehaviourFabIconAnnotation}
  dark={floatingButtonBehaviourFabIconAnnotationDark}
  alt=""
/>

## Usage Guidelines

### Chose one action to emphasize

- **Don’t**: stack multiple FAB over your content.
- **Do**: choose one main action or store them in a FAB - Drawer.

<ThemedImage
  light={floatingButtonUsageGuidelinesChoseOneActionToEmphasize}
  dark={floatingButtonUsageGuidelinesChoseOneActionToEmphasizeDark}
  alt=""
/>

### Be as concise as you can

- **Don’t**: write very long sentences for your actions.
- **Do**: either chose wisely one icon or shorten your text to be direct.

<ThemedImage
  light={floatingButtonUsageGuidelinesBeAsConciseAsYouCan}
  dark={floatingButtonUsageGuidelinesBeAsConciseAsYouCanDark}
  alt=""
/>

### Select a color that contrast with your interface

- **Don’t**: chose a FAB with a background close to your interface’s theme.
- **Do**: accentuate the contrast by choosing a color that your users will see without effort.

<ThemedImage
  light={floatingButtonUsageGuidelinesSelectAColorThatContrastWithYourInterface}
  dark={
    floatingButtonUsageGuidelinesSelectAColorThatContrastWithYourInterfaceDark
  }
  alt=""
/>

### Gather FAB to minimize eye strain

- **Don’t**: scatter actions and force the user to navigate the entire screen.
- **Do**: bring everything together in one place with consistent actions.

<ThemedImage
  light={floatingButtonUsageGuidelinesGatherFabToMinimizeEyeStrain}
  dark={floatingButtonUsageGuidelinesGatherFabToMinimizeEyeStrainDark}
  alt=""
/>

### Isolate FABs to avoid confusion

- **Don’t**: displaying a FAB near another action area, making it difficult to access.
- **Do**: put the FAB in an area where it is easily recognizable.

<ThemedImage
  light={floatingButtonUsageGuidelinesIsolateFabsToAvoidConfusion}
  dark={floatingButtonUsageGuidelinesIsolateFabsToAvoidConfusionDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=21944-519388&t=244StnnCdoCtO9oW-4)



# Group Buttons

Group Buttons consist of a group of buttons that are visually grouped together to represent a set of related actions or options.



## Overview

Group Buttons consist of a group of buttons that are visually grouped together to represent a set of related actions or options.

When a button in the group is selected, the selected state is visually highlighted. This can be used for selecting one item among others, renderings of multi-select, as in a style for selecting multiple exposed items in a form or list, or as filters.

### Usage

When to use:

- Use Group Buttons when you have a set of related options and want to allow users to select one or many options from the group.
- Use Group Buttons when you want to provide a visual appealing and interactive way for users to make a selection, or change a view.

When not to use:

- Avoid using Group Buttons when the options in the group are unrelated or independent. In such cases, consider using separate buttons.
- It is not recommended to use Group Buttons for navigation purposes, as this component is primarily designed for input or selection. In such cases, consider using other UI elements like tabs.
- Don’t use Group Buttons when you have too many actions: separate them into multiple Group Buttons or use a Dropdown instead to overwhelm them.

## Anatomy

The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it.

<ThemedImage
  light={groupButtonsAnatomy}
  dark={groupButtonsAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Group Buttons

| Property        | Values                          | Default    |
| --------------- | ------------------------------- | ---------- |
| **size**        | small / medium / large / xlarge | medium     |
| **variant**     | outline / ghost                 | outline    |
| **type**        | text / icon                     | label      |
| **color**       | primary / neutral / white       | primary    |
| **orientation** | horizontal / vertical           | horizontal |
| **spacing**     | false / true                    | false      |
| **fullWidth**   | false / true                    | false      |
| **3,4,5,6,7,8** | boolean                         | 3          |

#### ◇❖ Sub-component: Group Buttons - Button

| Property           | Values                       | Default    |
| ------------------ | ---------------------------- | ---------- |
| **size**           | small / medium / large       | medium     |
| **active**         | false / true                 | false      |
| **activeEmphasis** | medium / high                | medium     |
| **type**           | text / icon                  | text       |
| **style**          | outline / ghost              | outline    |
| **color**          | primary / neutral / white    | primary    |
| **orientation**    | horizontal / vertical        | horizontal |
| **position**       | start / between / end / full | start      |
| **◇ Button**       | Nested properties            | --         |
| **◇ Icon Button**  | Nested properties            | --         |

#### ◇ Nested properties: [Button](/docs/components/button)

#### ◇ Nested properties: [Icon Button](/docs/components/button#icon-buttons)

## Behaviour

Component behaviour helps to present the states and use cases that the component might encounter.

### Group Buttons

#### Size

Group buttons exist with 3 different sizes (small, medium and large) to provide flexibility in visual hierarchy and adapt to different layout requirements.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsSize}
  dark={groupButtonsBehaviourGroupButtonsSizeDark}
  alt=""
/>

#### Variants

Group buttons can be designed with an outline or ghost variant, which provide different visual styles for buttons, allowing designers to create varied and distinct button styles to suit different design needs.

**Outline**: Outline variants are designed with a border around the buttons, providing a clear visual separation from the background and other elements on the screen. They can be used for various purposes, such as primary actions, secondary actions, or for buttons that need to stand out in a particular context.

**Ghost**: Ghost variants are designed with a transparent background, allowing the background or the content underneath the buttons to be visible, while still providing a clear visual indication of the button's presence. Ghost buttons have a subtle and understated appearance, and they can be used for various purposes, such as for secondary actions, or for buttons that need to blend in with the surrounding content.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsVariants}
  dark={groupButtonsBehaviourGroupButtonsVariantsDark}
  alt=""
/>

#### Colors

Group buttons can be designed with different color variants to provide visual hierarchy and convey different meanings or actions to users. The primary, neutral, and white color variants offer distinct visual styles that can be used for different design purposes :

**Primary**: The primary color is typically used to convey the main action or primary call-to-action in a user interface. Primary buttons often have a bold and prominent appearance, drawing the user's attention and encouraging them to take the intended action.

**Neutral**: Neutral buttons provide a more subdued and understated appearance, and are often used for secondary actions or for buttons that are less prominent but still important in the user interface.

**White**: White color variants are designed with a contrasting color palette, such as primary or dark background. Please note that the white variant is designed for light theme only and may not be suitable for dark theme usage. If you need to design for dark theme, use the component from the dark theme library.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsColors}
  dark={groupButtonsBehaviourGroupButtonsColorsDark}
  alt=""
/>

#### Type

We provide you two types of Group Buttons:

**Text Group Buttons**: Text group buttons are a type of group of buttons, each containing text labels. Text group buttons are designed to convey information and provide clear and concise labels to help users understand the purpose of each button.

**Icon Group Buttons**: Icon group buttons are another type of a group of buttons, each containing icons or graphical symbols. These buttons are designed to convey actions or commands through visual representations rather than text labels. To enhance accessibility, tooltips can be added to provide additional context or descriptions for the icons.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsType}
  dark={groupButtonsBehaviourGroupButtonsTypeDark}
  alt=""
/>

#### Orientation

Group buttons can be designed with different orientations, including **horizontal** and **vertical**, to suit different layout requirements.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsOrientation}
  dark={groupButtonsBehaviourGroupButtonsOrientationDark}
  alt=""
/>

#### Spacing

You can choose between a clustered arrangement, where the buttons are placed close together with no spacing between them, or a spaced-out arrangement, where the buttons are spaced apart with a gap between them.

**Clustered**: Use when you want to group related buttons closely together, such as for a set of related actions or filters.

**Spacing**: Use when you want to visually separate the buttons from each other, such as for a navigation menu or a set of mutually exclusive options.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsSpacing}
  dark={groupButtonsBehaviourGroupButtonsSpacingDark}
  alt=""
/>

#### Full Width

The full width property determines how the buttons are sized in relation to the container they are placed in. You can choose between a hug content option, where the buttons are sized to fit their contents with no extra space on either side, or a full width option, where the buttons are stretched to fill the entire available width with equal spacing on either side.

**Hug content**: Use when you want the button width to match the content width, such as for a short label or icon-only button.

**Full width**: Use when you want the buttons to span the full width of the container, such as for a call-to-action button or a tab navigation.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsFullWidth}
  dark={groupButtonsBehaviourGroupButtonsFullWidthDark}
  alt=""
/>

### Group Buttons: Button

#### Active

Description about the behaviour, including any relevant links from research and internal Thales use cases.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsButtonActive}
  dark={groupButtonsBehaviourGroupButtonsButtonActiveDark}
  alt=""
/>

#### Active emphasis

The active emphasis property determines how the active button is visually distinguished from the other buttons in the group when active.

**Medium emphasis**: Use when you want to visually differentiate the active button from the other buttons, but not to the point of overwhelming them.

**High emphasis**: Use when you want to draw significant attention to the active button.

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsButtonActiveEmphasis}
  dark={groupButtonsBehaviourGroupButtonsButtonActiveEmphasisDark}
  alt=""
/>

#### Position

The position property of a button within the group determines its visual position relative to the other buttons in the group.

**Start**: The button is aligned to the left edge of the group

**Between**: The button is aligned between other buttons in the group

**End**: The button is aligned to the right edge of the group

**Full**: The button is full

<ThemedImage
  light={groupButtonsBehaviourGroupButtonsButtonPosition}
  dark={groupButtonsBehaviourGroupButtonsButtonPositionDark}
  alt=""
/>

## Usage Guidelines

Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts.

### Appearance

#### Maintain visual consistency among Group buttons

- **Don’t**: Mix different button types or colors within the same Group Buttons component, as this can create visual clutter and confusion for users.
- **Do**: Consistently use one style for all buttons within a Group Buttons component.

<ThemedImage
  light={
    groupButtonsUsageGuidelinesAppearanceMaintainVisualConsistencyAmongGroupButtons
  }
  dark={
    groupButtonsUsageGuidelinesAppearanceMaintainVisualConsistencyAmongGroupButtonsDark
  }
  alt=""
/>

#### Use icons with label only to reinforce action

- **Don’t**: Avoid using icons in action buttons for merely aesthetic purposes and icons that do not intuitively reinforce the action of the button.
- **Do**: Icons may be used in combination with button group text labels to further reinforce the explanation of the setting or view associated with interacting with the button.

<ThemedImage
  light={
    groupButtonsUsageGuidelinesAppearanceUseIconsWithLabelOnlyToReinforceAction
  }
  dark={
    groupButtonsUsageGuidelinesAppearanceUseIconsWithLabelOnlyToReinforceActionDark
  }
  alt=""
/>

**Note**: You can add a left icon for Group Buttons - Button by editing its nested properties.

#### Icon position for labels

- **Don’t**: Position icon to the right, as this may disrupt the typical reading direction and create confusion for users.
- **Do**: Align icon to the left as it is the typical reading direction for most languages, and helps to create a clear visual hierarchy for the user.

<ThemedImage
  light={groupButtonsUsageGuidelinesAppearanceIconPositionForLabels}
  dark={groupButtonsUsageGuidelinesAppearanceIconPositionForLabelsDark}
  alt=""
/>

#### Wrapping label

- **Don’t**: Wrap label text onto multiple lines, as this can disrupt the visual flow of the buttons and reduce their effectiveness.
- **Do**: Keep the label text for each button to a single line to maintain a consistent and visually balanced layout, improving the readability of the buttons.

<ThemedImage
  light={groupButtonsUsageGuidelinesAppearanceWrappingLabel}
  dark={groupButtonsUsageGuidelinesAppearanceWrappingLabelDark}
  alt=""
/>

### Arrangement

#### Arrange buttons in logical order

- **Don’t**: Use inconsistent or illogical ordering of the buttons, as this can create confusion and frustration for the user. This order can vary depending on the product and user needs.
- **Do**: Do consider the relative importance of each button, and order them accordingly. For example, more frequently used or higher-priority actions should be placed first.

<ThemedImage
  light={groupButtonsUsageGuidelinesArrangementArrangeButtonsInLogicalOrder}
  dark={groupButtonsUsageGuidelinesArrangementArrangeButtonsInLogicalOrderDark}
  alt=""
/>

#### Multiple Groups Buttons arrangement

- **Don’t**: Bury important primary actions among less important secondary actions
- **Do**: Position primary actions at first, and differentiate them from secondary actions.

<ThemedImage
  light={groupButtonsUsageGuidelinesArrangementMultipleGroupsButtonsArrangement}
  dark={
    groupButtonsUsageGuidelinesArrangementMultipleGroupsButtonsArrangementDark
  }
  alt=""
/>

**Note**: Use multiple Group Buttons with dividers to organize related actions or options into sections, making it easier for users to find what they need.

### Examples and recommendations of usage

#### Single Select

Single selection allows users to choose only one option from a group of buttons at a time. This is useful when the options are mutually exclusive, and the user needs to select only one option. In a single selection group button, selecting one button automatically deselects any previously selected button.

<ThemedImage
  light={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelect
  }
  dark={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelectDark
  }
  alt=""
/>

#### Multi Select

Multi-selection allows users to choose more than one option from a group of buttons. This is useful when the options are not mutually exclusive, and the user needs to select multiple options simultaneously. In a multi-selection group button, selecting one button does not automatically deselect any previously selected button. Users can select multiple options until they have made all the desired choices.



#### Single Select Group Button vs Toggle switch

- **Don’t**: Avoid using Group buttons for a single setting such as On/Off.
- **Do**: Instead, consider using a [toggle switch](/docs/components/toggle-switch).

<ThemedImage
  light={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelectGroupButtonsVsToggleSwitch
  }
  dark={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelectGroupButtonsVsToggleSwitchDark
  }
  alt=""
/>

#### Single Select Group Button vs Dropdown select

- **Don’t**: use Group Button for a large amount of options
- **Do**: Instead, consider using a [Dropdown Select](/docs/components/dropdown-select).

<ThemedImage
  light={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelectGroupButtonVsDropdownSelect
  }
  dark={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageSingleSelectGroupButtonVsDropdownSelectDark
  }
  alt=""
/>

#### Don’t use Group Buttons for navigation purposes

- **Don’t**: Use group buttons for site navigation.
- **Do**: Consider using [Tabs](/docs/components/tabs)  since they are better suited for navigation, as they provide a consistent and intuitive way for users to move between different sections or pages on a website or application.

<ThemedImage
  light={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageDonTUseGroupButtonsForNavigationPurposes
  }
  dark={
    groupButtonsUsageGuidelinesExamplesAndRecommendationsOfUsageDonTUseGroupButtonsForNavigationPurposesDark
  }
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=30198-547199&t=244StnnCdoCtO9oW-4)



# Dropdown Menu

<ThemedImage light={dropdownMenu} dark={dropdownMenuDark} alt="" />

## Overview

A Dropdown Menu displays a list of actions or options to a user.

### Usage

When to use:

- Users need to select one item exclusively from a short list of options (for example, fewer than 12 items).
- The values of the option list contain secondary information that does not need to be displayed right away.

When not to use:

- Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [Toggle Switch](/docs/components/toggle-switch) control instead.
- Users need to pick one item from a large set of options. In this case, you should consider using the [Combo Box](/docs/components/combo-box) instead.
- Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using [Radio Buttons](/docs/components/radio-button) or a [Radio Button Group](/docs/components/radio-button) instead.
- Do not nest dropdowns or use them to display overly complex information. Keep option selections as straight forward as possible.

### Sources and references

- [10 Ways to Improve Dropdowns in UI & UX Design](https://uxdesign.cc/10-ways-to-improve-dropdowns-in-ui-ux-design-59d61a304b70) - UX Design
- [Dropdowns](https://getbootstrap.com/docs/4.3/components/dropdowns/#overview) - Bootstrap
- [Dropdown Menu](https://atlassian.design/components/dropdown-menu/examples) - Atlassian
- [Menus](https://m3.material.io/components/menus/) - Material Design
- [Popover](https://spectrum.adobe.com/page/popover/) - Adobe Spectrum
- [Popper.js](https://popper.js.org/) - Popper
- [Dropdown](https://www.carbondesignsystem.com/components/dropdown/usage) - IBM Carbon
- [Web components punch list](https://www.tpgi.com/web-components-punch-list/) - TPGi
- [Alice Bartlett: Burn your select tags - EpicFEL 2014](https://www.youtube.com/watch?v=CUkMCQR4TpY) - YouTube
- [Dropdown](https://developer.microsoft.com/en-us/fluentui#/controls/web/dropdown) - Microsoft Fluent UI Web
- [Action list](https://polaris-react.shopify.com/components/actions/action-list) - Shopify Polaris
- [Combo Box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Design System

## Anatomy

<ThemedImage
  light={dropdownMenuAnatomy}
  dark={dropdownMenuAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Dropdown Menu

| Property       | Values                                           | Default |
| -------------- | ------------------------------------------------ | ------- |
| **size**       | small / medium / large                           | medium  |
| **items**      | 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 | 6       |
| **scrollable** | true / false                                     | false   |

#### ❖ Sub-component: Dropdown Menu Item

| Property         | Values                              | Default         |
| ---------------- | ----------------------------------- | --------------- |
| **size**         | small / medium / large              | medium          |
| **state**        | default / hover / focused / pressed | default         |
| **active**       | true / false                        | false           |
| **disabled**     | true / false                        | false           |
| **hasCheckbox**  | boolean                             | true            |
| **hasIcon**      | boolean                             | true            |
| **icon**         | instance swap                       | person          |
| **hasLabel**     | text                                | “dropdown item” |
| **hasCaption**   | boolean                             | true            |
| **caption**      | text                                | “caption”       |
| **rightContent** | boolean                             | true            |

## Behaviour

### Size

Dropdowns are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium dropdown is typically used for desktop/tablet devices. But for mobile devices, it is advised that you upscale the dropdown, to increase the touch area and make sure you reach the minimum requirements considering your target screen size and density.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={dropdownMenuBehaviourSize}
  dark={dropdownMenuBehaviourSizeDark}
  alt=""
/>

### Sorting

Items in a dropdown list should be sorted in the most logical way for the user. The following options are suggested when considering which sorting method to use…

- Logical: sorted into a meaningful order such as days of the week.
- Alphabetical: sort names, and similar content alphabetically.
- Numeric: sort numeric values into a sequential order, with the lowest number first.
- Chronological: sort time-related information into chronological order, with the most recent first.



### Text overflow

When a dropdown menu item label is too long for the available horizontal space, they wrap to form another line.

The field text itself truncates at the end, but the text can be shown in full in the dropdown menu.

<ThemedImage
  light={dropdownMenuBehaviourTextOverflow}
  dark={dropdownMenuBehaviourTextOverflowDark}
  alt=""
/>

### Position

Menus should be positioned relative to the edge of the screen or browser.

They typically appear next to (or in front of) the element that generates them. If they are in a position to be cut off by the browser or screen’s edge, the menu can instead appear to the left, right, or above the element that generates it.

<ThemedImage
  light={dropdownMenuBehaviourPosition}
  dark={dropdownMenuBehaviourPositionDark}
  alt=""
/>

### Scrolling

Menus can be scrollable if not all menu items are shown at once. In this state, menus show a persistent scroll bar. However, scroll bars may not always be enabled so we recommend showing 50% of the last item’s container height to indicate there is more to see within the menu.

<ThemedImage
  light={dropdownMenuBehaviourScrolling}
  dark={dropdownMenuBehaviourScrollingDark}
  alt=""
/>

## Usage Guidelines

### Keep menu items concise

- **Don’t**: use lots of text to describe the action behind a menu item in the dropdown. It will cause the text to wrap making it difficult for the user to quickly scan the list.
- **Do**: keep the label in the dropdown menu item short and concise.

<ThemedImage
  light={dropdownMenuUsageGuidelinesKeepMenuItemsConcise}
  dark={dropdownMenuUsageGuidelinesKeepMenuItemsConciseDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284233&t=244StnnCdoCtO9oW-4)



# Alert & Toast

<ThemedImage light={alertToast} dark={alertToastDark} alt="" />

## Overview

- Alerts inform the user of important information or important action required. They are non-disruptive to a user's experience and do not require to interrupt the user’s task.
- Toasts are temporary pop-up alerts that displays briefly on the screen to provide feedback or information to the user. Toasts can be closed by the user or can automatically disappear after a set amount of time.

### Usage

When to use:

- Use alerts/toasts when displaying a highlight, a message to confirm an action, an error and make someone aware of important information.
- When you do not want to interrupt users while they are performing an action.

When not to use:

- When you need to interrupt users while they are performing an action.
- You want to make sure that users read the message before they leave the page.

## Anatomy

<ThemedImage light={alertToastAnatomy} dark={alertToastAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Alert

| Property            | Values                                            | Default        |
| ------------------- | ------------------------------------------------- | -------------- |
| **size**            | small / medium / large                            | medium         |
| **severity**        | informative / neutral / success / warning / error | informative    |
| **emphasis**        | low / medium / high                               | low            |
| **leftIcon**        | instance swap                                     | true           |
| **informativeIcon** | instance swap                                     | info           |
| **successIcon**     | instance swap                                     | check_circle   |
| **warningIcon**     | boolean                                           | warning_amber  |
| **errorIcon**       | instance swap                                     | error_outline  |
| **hasTitle**        | boolean                                           | false          |
| **title**           | text                                              | title          |
| **message**         | text                                              | Alert message. |
| **rightActions**    | boolean                                           | true           |
| **actionButton**    | boolean                                           | true           |
| **dismissible**     | boolean                                           | true           |

#### ❖ Sub-Component: Button

Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

#### ❖ Sub-Component: Icon Button

Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

#### ◇❖ Toast

| Property           | Values                    | Default |
| ------------------ | ------------------------- | ------- |
| **slideDirection** | none / ↑ / ↓ / ← / →      | none    |
| **dismissible**    | false / true              | true    |
| **hidden**         | false / true              | false   |
| **◇ Alert**        | → Alert nested properties |         |

## Behaviour

Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

### Low / Medium / High emphasis

The Quantum supports three levels of emphasis style alerts. High-emphasis alerts are best for critical messaging while low-emphasis and mid-emphasis alerts are less visually disruptive for users.

It’s up to the product team to decide which notification style to use in their product. However, it is important to not mix the styles when they are applied at the same level hierarchy. When in doubt, use low-contrast notifications.

<ThemedImage
  light={alertToastBehaviourLowMediumHighEmphasis}
  dark={alertToastBehaviourLowMediumHighEmphasisDark}
  alt=""
/>

### Neutral variant

The neutral variant is the default alert option. It uses the Quantum bluegrey and does not have an icon. This is used when the message is neutral in tone or when its semantics do not fit in any of the other variants.

Note: this variant also uses the general interaction states such as hover, active, focused.

<ThemedImage
  light={alertToastBehaviourNeutralVariant}
  dark={alertToastBehaviourNeutralVariantDark}
  alt=""
/>

### Informative variant

The informative alert uses the informative semantic colour (primary) and has an info icon to help those with colour vision deficiency discern the message tone. Similar to the call to action button, this should be used when the message should call extra attention compared to the neutral variant.

Note: this variant also utilises the general interaction states such as hover, active, focused.

<ThemedImage
  light={alertToastBehaviourInformativeVariant}
  dark={alertToastBehaviourInformativeVariantDark}
  alt=""
/>

### Success variant

The success alert uses the positive semantic colour (green) and has a checkmark icon to help those with colour vision deficiency discern the message tone. This can be used to inform the user of a successful operation.

Note: this variant also utilises the general interaction states such as hover, active, focused.

<ThemedImage
  light={alertToastBehaviourSuccessVariant}
  dark={alertToastBehaviourSuccessVariantDark}
  alt=""
/>

### Warning variant

The warning alert uses the warning semantic colour (orange) and has an warning icon to help those with colour vision deficiency to discern the message tone. This can be used to show an attention point to the user.

Note: this variant also utilises the general interaction states such as hover, active, focused.

<ThemedImage
  light={alertToastBehaviourWarningVariant}
  dark={alertToastBehaviourWarningVariantDark}
  alt=""
/>

### Error variant

The error alert uses the error semantic colour (red) and has an alert icon to help those with colour vision deficiency to discern the message tone. This can be used to show an attention point to the user.

Note: this variant also utilises the general interaction states such as hover, active, focused.

<ThemedImage
  light={alertToastBehaviourErrorVariant}
  dark={alertToastBehaviourErrorVariantDark}
  alt=""
/>

### Action

An alert can have up to one button, to ensure consistency and maintain focus on the message being presented to the user. This means that the button can only be used if its action directly relates to the message.

Note: the dismissible button is not considered as an action in the same context, therefore you can have a dismissible button and a single action in one alert.

<ThemedImage
  light={alertToastBehaviourAction}
  dark={alertToastBehaviourActionDark}
  alt=""
/>

### Links

An alert message may also contain a link that directly relates to a file or location in which an action has either successfully or unsuccessfully been achieved. For example:

> All files archived. Find archived files in [My Documents](#).

This can only be used if an action is not already in place.

<ThemedImage
  light={alertToastBehaviourLinks}
  dark={alertToastBehaviourLinksDark}
  alt=""
/>

### Toast

#### Slide direction

When disappearing, toasts can slide out from different directions, depending on the design requirements and the desired user experience.

It is recommended to use the same slide direction as the position of the toast for avoiding obstruction of the content on the screen when it disappears.

<ThemedImage
  light={alertToastBehaviourToastSlideDirection}
  dark={alertToastBehaviourToastSlideDirectionDark}
  alt=""
/>

#### Dismissible / Non-dismissible

- Dismissible toasts provide a close button or icon for the user to manually dismiss the toast if desired. You can also add a time-out to make it disappear after a set duration of time.
- Non-dismissible toasts automatically disappear after a a set duration of time. They provide a convenient way for the user to quickly view and take into account the message, without having to take any action to dismiss the toast.

<ThemedImage
  light={alertToastBehaviourToastDismissibleNonDismissible}
  dark={alertToastBehaviourToastDismissibleNonDismissibleDark}
  alt=""
/>

#### Change the toast duration

You can change the timer to dismiss the toast after a set amount of time has elapsed :

- Select the toast (Non-dismissible)
- Go to Prototype > Variant interactions > Delay
- Change the “After delay” timer to the desired time-out time

As a general rule, toasts should be displayed for just enough time to allow the user to read the content, but not long enough to become annoying or obstructive.

A common recommendation for the duration of a toast is 3-5 seconds. For toasts that display critical or important information, a longer duration may be appropriate, while for toasts that display simple confirmation messages, a shorter duration may be sufficient.

<ThemedImage
  light={alertToastBehaviourToastChangeTheToastDuration}
  dark={alertToastBehaviourToastChangeTheToastDurationDark}
  alt=""
/>

## Usage Guidelines

### Alert or Toast?

- **Alert**: Alerts should be used sparingly to highlight important information that requires the user's attention, without interrupting the user's current task. These alerts can either remain visible permanently or disappear once the user takes action, such as clicking a button.
- **Toast**: use Toasts for temporary confirmation, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience. Toasts automatically disappear after a set duration, or can be dismissed by the user by clicking on a button.

<ThemedImage
  light={alertToastUsageGuidelinesAlertOrToast}
  dark={alertToastUsageGuidelinesAlertOrToastDark}
  alt=""
/>

### Alert or modal dialog?

- **Don’t**: use a Modal Dialog to present a simple notification as it will distract the users attention, interrupting the user experience. Dialog is only ideal when a situation requires the user’s attention, either for displaying important information or prompting for a response.
- **Do**: use Toasts for confirmation, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience.

<ThemedImage
  light={alertToastUsageGuidelinesAlertOrModalDialog}
  dark={alertToastUsageGuidelinesAlertOrModalDialogDark}
  alt=""
/>

### Use one action only

- **Don’t**: display more than one action in an alert, it can overwhelm and distract the user.
- **Do**: use only one action to focus the user’s attention on the message in the alert.

<ThemedImage
  light={alertToastUsageGuidelinesUseOneActionOnly}
  dark={alertToastUsageGuidelinesUseOneActionOnlyDark}
  alt=""
/>

### Use sentence case

- **Don’t**: use any other text formatting such as capitalization, as it can affect the users emotional reaction, slows down the reading and can either engage or repel them.
- **Do**: use sentence case as it is easier to read, and more natural when reading.

<ThemedImage
  light={alertToastUsageGuidelinesUseSentenceCase}
  dark={alertToastUsageGuidelinesUseSentenceCaseDark}
  alt=""
/>

### Overuse of alerts

- **Don’t**: Overuse alerts, too many alerts is annoying and obstructive and can lead users to disregard them.
- **Do**: Use alerts sparingly and only to highlight information that requires the user’s attention.

<ThemedImage
  light={alertToastUsageGuidelinesOveruseOfAlerts}
  dark={alertToastUsageGuidelinesOveruseOfAlertsDark}
  alt=""
/>

### Avoid stacking multiple toasts

Quantum recommends presenting single toasts as opposed to stacking or overlaying. However, we do recognise that sometimes toasts are consecutively or simultaneously triggered and so they must be presented somehow - in this case, we recommend the stacked approach.

<ThemedImage
  light={alertToastUsageGuidelinesAvoidStackingMultipleToasts}
  dark={alertToastUsageGuidelinesAvoidStackingMultipleToastsDark}
  alt=""
/>

### Examples of usage

#### Alerts as a banner

You can use alerts as a banner to display non-critical information or messages that do not require immediate action from the user.

<ThemedImage
  light={alertToastUsageGuidelinesExamplesOfUsageAlertsAsABanner}
  dark={alertToastUsageGuidelinesExamplesOfUsageAlertsAsABannerDark}
  alt=""
/>

#### Alerts in notifications

You can use alerts in notifications to inform the user of important information or events that require their attention.

<ThemedImage
  light={alertToastUsageGuidelinesExamplesOfUsageAlertsInNotifications}
  dark={alertToastUsageGuidelinesExamplesOfUsageAlertsInNotificationsDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=16305-478406&t=244StnnCdoCtO9oW-4)



# Modal Dialog

<ThemedImage light={modalDialog} dark={modalDialogDark} alt="" />

## Overview

A Modal Dialog focuses the user’s attention exclusively on one task or piece of information via a window that sits on top of the page content. It does this by disabling the main content until the user explicitly interacts with the modal dialog.

- Modal dialog should be used when you need to:
- Grab the user’s attention
- Get input from the user

### Usage

When to use :

- Grab the user’s attention
- Get input from the user

## Anatomy

<ThemedImage light={modalDialogAnatomy} dark={modalDialogAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Component: Dialog Box

| Property             | Values                 | Default |
| -------------------- | ---------------------- | ------- |
| **size**             | small / medium / large | medium  |
| **content**          | custom / textArea      | custom  |
| **verticalResizing** | true / false           | false   |

#### ❖ Sub-Component: Header

| Property        | Values                 | Default |
| --------------- | ---------------------- | ------- |
| **size**        | small / medium / large | medium  |
| **hasLeftIcon** | boolean                | true    |
| **hasCaption**  | boolean                | true    |
| **dismissible** | boolean                | true    |

#### ❖ Sub-Component: Footer

| Property            | Values                 | Default    |
| ------------------- | ---------------------- | ---------- |
| **size**            | small / medium / large | medium     |
| **alignment**       | horizontal / vertical  | horizontal |
| **divider**         | boolean                | true       |
| **primaryAction**   | boolean                | true       |
| **secondaryAction** | boolean                | true       |
| **tertiaryAction**  | boolean                | false      |

## Behaviour

### Choosing an escaping pattern

The header is customizable and you can easily turn on and off the presence of the close button. By doing so, you must consider choosing and documenting in your designs the right escape pattern:

- Pressing **‘x’** button
- Pressing **‘ESC’** on the keyboard
- Clicking outside of the dialog box
- Using a **‘Cancel’** option

<ThemedImage
  light={modalDialogBehaviourChoosingAnEscapingPattern}
  dark={modalDialogBehaviourChoosingAnEscapingPatternDark}
  alt=""
/>

### Customize content

To swap the default content with your own, follow these simple steps:

1. **Create your composition in a frame and apply Auto layout to it**
2. **Create a local component with this frame**
3. **Drag & drop it from your assets panel while pressing CTRL+ALT or CMD+OPT to swap the default content**
4. **Make sure to apply the right constraints for resizing the lower components in the content area**

<ThemedImage
  light={modalDialogBehaviourCustomizeContent}
  dark={modalDialogBehaviourCustomizeContentDark}
  alt=""
/>

### Action buttons group

A dialog can have up to 3 buttons in its footer compartment.

When horizontal space is limited, button groups stack vertically. They should appear in ascending order based on importance, with the most critical action at the bottom.

<ThemedImage
  light={modalDialogBehaviourActionButtonsGroup}
  dark={modalDialogBehaviourActionButtonsGroupDark}
  alt=""
/>

### Manual resizing (Vertical)

The modal component comes in 2 versions when it comes to resizing:

- Automatic sizing based on the content you will put in the swap zone. (default)
- Manual override to manage yourself the vertical size of the dialog box.

<ThemedImage
  light={modalDialogBehaviourManualResizingVertical}
  dark={modalDialogBehaviourManualResizingVerticalDark}
  alt=""
/>

### Overlay or Scrim

To focus the attention on the modal and indicate that any interaction with the main content behind is disabled, the modal includes an overlay or scrim layer. The overlay sits right behind the modal and cover the full page.

The overlay uses the color black-30: black color with a transparency of 30%.

<ThemedImage
  light={modalDialogBehaviourOverlayOrScrim}
  dark={modalDialogBehaviourOverlayOrScrimDark}
  alt=""
/>

## Usage Guidelines

### Naming your dialog

- **Don’t**: use dialog titles that pose an ambiguous question to the user.
- **Do**: name a dialog with a specific question or statement that concisely explains what’s involved in the request, and provides clear actions.

<ThemedImage
  light={modalDialogUsageGuidelinesNamingYourDialog}
  dark={modalDialogUsageGuidelinesNamingYourDialogDark}
  alt=""
/>

### Naming your actions

- **Don’t**: name your actions with ambiguous words, otherwise it creates a sense of doubt to the user.
- **Do**: name actions with specific and actionable words, allowing the user to make a confident decision.

<ThemedImage
  light={modalDialogUsageGuidelinesNamingYourActions}
  dark={modalDialogUsageGuidelinesNamingYourActionsDark}
  alt=""
/>

### Provide important information

- **Don’t**: make things unclear about the impact for the user.
- **Do**: clearly state what the action taken will impact from the user’s perspective.

<ThemedImage
  light={modalDialogUsageGuidelinesProvideImportantInformation}
  dark={modalDialogUsageGuidelinesProvideImportantInformationDark}
  alt=""
/>

### Don’t stack dialog boxes

- **Don’t**: make a dialog appear on top of another.
- **Do**: avoid visual complexity by sticking to one dialog at a time.

<ThemedImage
  light={modalDialogUsageGuidelinesDonTStackDialogBoxes}
  dark={modalDialogUsageGuidelinesDonTStackDialogBoxesDark}
  alt=""
/>

### Avoid multiple steps dialog

- **Don’t**: do multi step dialog. If the interaction is complex enough to have this many inputs or information to retrieve, it might be worth having its own page.
- **Do**: consider making it a dedicated page in the process.

<ThemedImage
  light={modalDialogUsageGuidelinesAvoidMultipleStepsDialog}
  dark={modalDialogUsageGuidelinesAvoidMultipleStepsDialogDark}
  alt=""
/>

## Layout Grid Examples

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284209&t=244StnnCdoCtO9oW-4)

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284217&t=244StnnCdoCtO9oW-4)



# Tooltip

<ThemedImage light={tooltip} dark={tooltipDark} alt="" />

## Overview

Tooltips are contextual, non-actionable and informative floating labels. They can be activated by hover, focus, or even click to display additional information to help the users understand something.
They should always be non-essential to the global understanding.

### Usage

When to use:

- When you want to display additional information for an interface element.
- To describe an icon when it is not labelled, such as the menu items in the [Rail](/docs/components/rail).

When not to use:

- Don’t use tooltips to display crucial information. This kind of information should always be accessible without any interaction from the users.
- To propose new actions: tooltips must **always** be informative only, and never actionable

## Anatomy

<ThemedImage light={tooltipAnatomy} dark={tooltipAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Tooltip

| Property        | Values                      | Default                           |
| --------------- | --------------------------- | --------------------------------- |
| **size**        | small / medium / large      | medium                            |
| **orientation** | left / right / bottom / top | left                              |
| **tipPosition** | start / center / end        | center                            |
| **lowContrast** | true / false                | false                             |
| **\*hasTitle**  | boolean                     | true                              |
| **\*title**     | text                        | “Tooltip title.”                  |
| **content**     | text                        | “Write the tooltip content here.” |

## Behaviour

### Sizes

Tooltips are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium tooltip is used typically for desktop. But for mobile devices, it is advised that you upscale the tooltip, to maximize the visual impact.

For more information about text sizes and readability, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={tooltipBehaviourSizes}
  dark={tooltipBehaviourSizesDark}
  alt=""
/>

### Tooltip title

Use the title property if you need to summarize a long description.

Therefore, we strongly recommend being as concise as possible to not strain the attention of the user in their business context.

<ThemedImage
  light={tooltipBehaviourTooltipTitle}
  dark={tooltipBehaviourTooltipTitleDark}
  alt=""
/>

### Tip direction

The tooltip component should always be positioned according to its target. The tip direction variants help you initiate this orientation.

Coupled with the tip position, this component caters for the diverse range of use cases and positions you might need to contextualize it.

Main directions include:

- Bottom
- Top
- Left
- Right

<ThemedImage
  light={tooltipBehaviourTipDirection}
  dark={tooltipBehaviourTipDirectionDark}
  alt=""
/>

### Tip position

The tooltip component should always be positioned according to its target.
The tip position variants help you complete the tip direction variant to be even more precise.

For all directions, the tip position options are:

- Start
- Center
- End

<ThemedImage
  light={tooltipBehaviourTipPosition}
  dark={tooltipBehaviourTipPositionDark}
  alt=""
/>

### Low contrast option

To lower the visual emphasis on the tooltip component, you can activate the Low contrast option. This option will apply a lighter background to the tooltip while remaining always accessible.

<ThemedImage
  light={tooltipBehaviourLowContrastOption}
  dark={tooltipBehaviourLowContrastOptionDark}
  alt=""
/>

## Usage Guidelines

### Tooltips aren’t made for crucial information.

- **Don’t**: hide information that is crucial to the experience.
- **Do**: always make them visible instead and use tooltip for additional information.

<ThemedImage
  light={tooltipUsageGuidelinesTooltipsAreNotMadeForCrucialInformation}
  dark={tooltipUsageGuidelinesTooltipsAreNotMadeForCrucialInformationDark}
  alt=""
/>

### Be as concise as possible

- **Don’t**: overflow the tooltip with too much information. Tooltips are supposed to carry additional information so avoid taking too much of your user’s attention.
- **Do**: keep the tooltips content 1 or 2 (short) sentences long.

<ThemedImage
  light={tooltipUsageGuidelinesBeAsConciseAsPossible}
  dark={tooltipUsageGuidelinesBeAsConciseAsPossibleDark}
  alt=""
/>

### Use orientation options to avoid obstructions

- **Don’t**: mask important information under a tooltip.
- **Do**: choose the best orientation option so the tooltip doesn’t obstruct helpful contextual information.

<ThemedImage
  light={tooltipUsageGuidelinesUseOrientationOptionsToAvoidObstructions}
  dark={tooltipUsageGuidelinesUseOrientationOptionsToAvoidObstructionsDark}
  alt=""
/>

### Use tip position options when constrained by the window’s edge/corner

- **Don’t**: resize the tooltip to bring the tip closer to its target.
- **Do**: Choose the right tip position to visually connect the tooltip with its target (start, center or end).

<ThemedImage
  light={
    tooltipUsageGuidelinesUseTipPositionOptionsWhenConstrainedByTheWindowsEdgeCorner
  }
  dark={
    tooltipUsageGuidelinesUseTipPositionOptionsWhenConstrainedByTheWindowsEdgeCornerDark
  }
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284177&t=244StnnCdoCtO9oW-4)



# Checkbox

<ThemedImage light={checkbox} dark={checkboxDark} alt="" />

## Overview

Checkboxes allow users to select multiple options from a list, or to mark an individual item as selected. They are often familiar to users, as checkboxes originated on paper forms and are incredibly useful for scanning a list of items before making one or more selections.

### Usage

When to use:

- Select one or more options from a list
- Present a list containing sub-selections
- Turn an item on or off

## Anatomy

<ThemedImage light={checkboxAnatomy} dark={checkboxAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Checkbox

| Property  | Values                 | Default |
| --------- | ---------------------- | ------- |
| **size**  | small / medium / large | medium  |
| **items** | 2 to 10                | 3       |
| **color** | primary / neutral      | primary |

#### ❖ Component: Checkbox

| Property          | Values                              | Default   |
| ----------------- | ----------------------------------- | --------- |
| **size**          | small / medium / large              | medium    |
| **color**         | primary / neutral                   | primary   |
| **state**         | default / hover / focused / pressed | default   |
| **checked**       | false / true                        | false     |
| **indeterminate** | false / true                        | false     |
| **error**         | false / true                        | false     |
| **disabled**      | false / true                        | false     |
| **\*hasLabel**    | boolean                             | true      |
| **label**         | text                                | “Label”   |
| **\*hasCaption**  | boolean                             | false     |
| **\*caption**     | text                                | “Caption” |

## Behavior

### Sizes

Checkboxes are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium checkbox is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the checkbox, to increase the touch area.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={checkboxBehaviourSizes}
  dark={checkboxBehaviourSizesDark}
  alt=""
/>

### Selection

Checkboxes can be unchecked, checked, or in an indeterminate state.

The indeterminate state is used when a value is neither selected or unselected. For example, a parent checkbox showing several checkbox children, with some checked and some unchecked.

<ThemedImage
  light={checkboxBehaviourSelection}
  dark={checkboxBehaviourSelectionDark}
  alt=""
/>

### Emphasis

By default, checkboxes are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a checkbox is required.

For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen.

<ThemedImage
  light={checkboxBehaviourEmphasis}
  dark={checkboxBehaviourEmphasisDark}
  alt=""
/>

### Error

Checkboxes can also have an error state to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid.

<ThemedImage
  light={checkboxBehaviourError}
  dark={checkboxBehaviourErrorDark}
  alt=""
/>

### Text overflow

When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this:

1. Set **‘Label Base’** layer to fill container (horizontally).
2. Set **‘input-and-label’** layer to fill container (horizontally).
3. Set **‘Checkbox - Base’** layer to fill container (horizontally).
4. Set **‘Checkbox’** layer to fill container (horizontally).
5. As a result of changing the layer in step 4 you will need to reset the **‘Checkbox - Base’** layer to fill container (horizontally).

<ThemedImage
  light={checkboxBehaviourTextOverflow}
  dark={checkboxBehaviourTextOverflowDark}
  alt=""
/>

### Internationalization

For RTL (right-to-left) languages, the layout of the checkbox is mirrored. The checkmark is placed on the right side of the text.

To build your own (BYO) version of this, either detach the **Checkbox** component or use the **Checkbox Input** component with the correct font scale and spacing as seen in the LTR version.

<ThemedImage
  light={checkboxBehaviourInternationalization}
  dark={checkboxBehaviourInternationalizationDark}
  alt=""
/>

## Usage Guidelines

### When to choose a checkbox over radio buttons

- **Don’t:** use checkbox groups if the selection only requires a single option from a list of mutually exclusive options.
- **Do:** use checkboxes when a user needs to select as many options as desired.

<ThemedImage
  light={checkboxUsageGuidelinesWhenToChooseACheckboxOverRadioButtons}
  dark={checkboxUsageGuidelinesWhenToChooseACheckboxOverRadioButtonsDark}
  alt=""
/>

### When to choose a checkbox over a switch

- **Don’t**: use a checkbox to communicate activation (e.g. on/off states) as they can have an error state and this could confuse users about the action they’re about to take.
- **Do**: use a checkbox for communicating selection.

<ThemedImage
  light={checkboxUsageGuidelinesWhenToChooseACheckboxOverASwitch}
  dark={checkboxUsageGuidelinesWhenToChooseACheckboxOverASwitchDark}
  alt=""
/>

### Label groups of related checkboxes

- **Don’t**: expect the users to understand a group of checkboxes, if they are not provided with a header or caption text.
- **Do**: provide a label with your checkboxes to describe what the list of options represents and guides the users in what to do. Especially for those using a screen reader.

<ThemedImage
  light={checkboxUsageGuidelinesLabelGroupsOfRelatedCheckboxes}
  dark={checkboxUsageGuidelinesLabelGroupsOfRelatedCheckboxesDark}
  alt=""
/>

### Representing mixed values

- **Don’t**: use the unchecked state for mixed state for sub-items.
- **Do**: use the indeterminate state to represent a mixed state for sub-items.

<ThemedImage
  light={checkboxUsageGuidelinesRepresentingMixedValues}
  dark={checkboxUsageGuidelinesRepresentingMixedValuesDark}
  alt=""
/>

### Concise labelling

- **Don’t**: use complicated labels.
- **Do**: use explicit and concise labels.

<ThemedImage
  light={checkboxUsageGuidelinesConciseLabelling}
  dark={checkboxUsageGuidelinesConciseLabellingDark}
  alt=""
/>

### Using the “other option”

- **Don’t**: force the user to choose an option they don’t want to.
- **Do**: add the input field component to support the “other option” if not all options are available in the list.

<ThemedImage
  light={checkboxUsageGuidelinesUsingTheOtherOption}
  dark={checkboxUsageGuidelinesUsingTheOtherOptionDark}
  alt=""
/>

### Text wrapping

- **Don’t**: not vertically centre wrapped text with the checkbox.
- **Do**: let the text wrap beneath the checkbox so the control and the label are top aligned.

<ThemedImage
  light={checkboxUsageGuidelinesTextWrapping}
  dark={checkboxUsageGuidelinesTextWrappingDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284169&t=kOWgyuqnVCEtliGV-4)



# Combo Box

<ThemedImage light={comboBox} dark={comboBoxDark} alt="" />

## Overview

Combo Boxes combine a text entry with a dropdown menu, allowing users to filter longer lists to only the selections matching a query.

### Usage

- Users need to select a single item from a long list of items.
- The values of the option list are secondary information and do not need to be displayed right away.
- You want to allow users to be able to quickly search or filter through the item list.

When not to use:

- Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [toggle switch](/docs/components/toggle-switch) control instead.

### Sources and references

- [Combo box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Fiori

## Anatomy

<ThemedImage light={comboBoxAnatomy} dark={comboBoxAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Combo Box

| Property     | Values                   | Default |
| ------------ | ------------------------ | ------- |
| **size**     | small / medium / large   | medium  |
| **state**    | default / hover / filled | default |
| **open**     | false / true             | false   |
| **error**    | true / false             | false   |
| **disabled** | false / true             | false   |

#### ◇❖ Sub-component: Text input

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

#### ◇❖ Sub-component: Dropdown menu

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

## Behaviour

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

### Sizes

Combo boxes are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page.

For example, if you are using a medium size combo box menu also use the same size text inputs, buttons, and so on.

<ThemedImage
  light={comboBoxBehaviourSizes}
  dark={comboBoxBehaviourSizesDark}
  alt=""
/>

### Filterable input

When the dropdown menu gets longer than 10-20 items, a searchable input can allow a user to search items easier through a large list of choices instead of scrolling down.

<ThemedImage
  light={comboBoxBehaviourFilterableInput}
  dark={comboBoxBehaviourFilterableInputDark}
  alt=""
/>

### Autosuggest & autocomplete

The two types of selection suggestion should not be confused.

- Autosuggestion: filters through the list of items to give the user a smaller range of options to choose from.
- Autocompletion: when the input field puts forward a way to complete the sentence or the word.

<ThemedImage
  light={comboBoxBehaviourAutosuggestAutocomplete}
  dark={comboBoxBehaviourAutosuggestAutocompleteDark}
  alt=""
/>

### Completed input

When the user has selected an option, the dropdown should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state.

When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**.

<ThemedImage
  light={comboBoxBehaviourCompletedInput}
  dark={comboBoxBehaviourCompletedInputDark}
  alt=""
/>

## Usage Guidelines

### Choosing radio buttons over dropdowns

- **Don’t**: use dropdowns for 5 options or less.
- **Do**: use radio buttons instead.

<ThemedImage
  light={comboBoxUsageGuidelinesChoosingRadioButtonsOverDropdowns}
  dark={comboBoxUsageGuidelinesChoosingRadioButtonsOverDropdownsDark}
  alt=""
/>
### Choosing text inputs over dropdowns

- **Don’t**: propose a dropdown if selecting an option takes more time than typing.
- **Do**: use text inputs (for example) instead.

<ThemedImage
  light={comboBoxUsageGuidelinesChoosingTextInputsOverDropdowns}
  dark={comboBoxUsageGuidelinesChoosingTextInputsOverDropdownsDark}
  alt=""
/>

### Avoid dropdowns for binary choices (On/Off - Yes/No - …)

- **Don’t**: make the user select between two binary and opposed options in a list.
- **Do**: use a toggle switch or a checkbox instead.

<ThemedImage
  light={comboBoxUsageGuidelinesAvoidDropdownsForBinaryChoices}
  dark={comboBoxUsageGuidelinesAvoidDropdownsForBinaryChoicesDark}
  alt=""
/>

### Avoid dropdowns for numeric choices

- **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …)

<ThemedImage
  light={comboBoxUsageGuidelinesAvoidDropdownsForNumericChoices}
  dark={comboBoxUsageGuidelinesAvoidDropdownsForNumericChoicesDark}
  alt=""
/>

- **Don’t**: give the user a too long, scrollable list of options to choose from without helping them.
- **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list.

<ThemedImage
  light={comboBoxUsageGuidelinesHelpTheUserForLongListsOfChoices}
  dark={comboBoxUsageGuidelinesHelpTheUserForLongListsOfChoicesDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284161&t=kOWgyuqnVCEtliGV-4)



# Date Picker

<ThemedImage light={datePicker} dark={datePickerDark} alt="" />

## Overview

Date Pickers are used when you have to select dates, whether dates are displayed in a calendar view or simply in an input field. They allow you to select a single value from a predetermined set, or a range of values depending on context.

### Usage

When to use:

- If you want users to indicate a single date or a range of dates.

When not to use:

- If the dates are really restrictive and could be filled with a predefined list or checkbox.

### Sources

- [Date-Input Form Fields](https://www.nngroup.com/articles/date-input/) by Nielsen Norman Group
- [Date picker](https://carbondesignsystem.com/components/date-picker/usage/) by Carbon Design System
- [Date Picker](https://mui.com/x/react-date-pickers/date-picker/) by MUI X
- [Datepicker](https://material.angular.dev/components/datepicker/overview) by Material Angular

## Anatomy

<ThemedImage light={datePickerAnatomy} dark={datePickerAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### Component: Date Picker

| Property         | Values                   | Default |
| ---------------- | ------------------------ | ------- |
| **size**         | small / medium / large   | medium  |
| **range**        | off / on                 | off     |
| **state**        | default / hover / filled | default |
| **color**        | neutral / primary        | primary |
| **error**        | false / true             | false   |
| **disabled**     | false / true             | false   |
| **showCalendar** | boolean                  | true    |
| **footer**       | boolean                  | true    |
| **caption**      | boolean                  | true    |

#### Component: Date Bounding Box

| Property        | Values                                         | Default |
| --------------- | ---------------------------------------------- | ------- |
| **size**        | small / medium / large                         | medium  |
| **color**       | primary / neutral                              | primary |
| **state**       | default / hover / focused / pressed / in range | default |
| **selected**    | false / true                                   | false   |
| **disabled**    | false / true                                   | false   |
| **label**       | text                                           | 1       |
| **current day** | boolean                                        | true    |
| **first date**  | boolean                                        | false   |
| **last date**   | boolean                                        | false   |

#### Component: Header Menu

| Property         | Values                                                 | Default        |
| ---------------- | ------------------------------------------------------ | -------------- |
| **size**         | small / medium / large                                 | medium         |
| **style**        | single picker / right range picker / left range picker | single picker  |
| **yearCalendar** | false / true                                           | false          |
| **dropdown**     | boolean                                                | true           |
| **label**        | text                                                   | “october 2022” |

## Behaviour

### Date Picker

#### Sizes

Date Picker exist with 3 different sizes: small, medium and large.

When the calendar is open, each nested component should be the same height as the date input field. Use a consistent size of form components on the same page.

For example, if you are using a medium size dropdown multiselect, also use the same size text inputs, buttons, and so on.

<ThemedImage
  light={datePickerBehaviourDatePickerSizes}
  dark={datePickerBehaviourDatePickerSizesDark}
  alt=""
/>

#### Range Picker

Range Picker should be used when the user is asked to specify a range of dates, for example for the dates of departure and return of a trip.

Range Picker is basically two Date Pickers joined.

First Child and Last Child properties should be used on selected state dates to produce a more realistic prototype.

<ThemedImage
  light={datePickerBehaviourDatePickerRangePicker}
  dark={datePickerBehaviourDatePickerRangePickerDark}
  alt=""
/>

#### Calendar

By default, the calendar is visible (On state), but it is possible to hide it and show only the date input label.

<ThemedImage
  light={datePickerBehaviourDatePickerCalendar}
  dark={datePickerBehaviourDatePickerCalendarDark}
  alt=""
/>

#### Footer

By default, Footer is not visible (Off state). When activated, it allows the user to control the date picker component with explicit action buttons, primary, secondary and tertiary buttons.

It offers the possibility to confirm or cancel the current selection, and use “Today” shortcut to return to today's date.

<ThemedImage
  light={datePickerBehaviourDatePickerFooter}
  dark={datePickerBehaviourDatePickerFooterDark}
  alt=""
/>

### Date Bounding Box

#### State

States, similar to the Button component are proposed to cover every use case.

<ThemedImage
  light={datePickerBehaviourDateBoundingBoxState}
  dark={datePickerBehaviourDateBoundingBoxStateDark}
  alt=""
/>

#### Current Day

By default, current day state is deactivated within a Date Picker component. The indication is materialized by a dot under the day number.

The goal is to allow the user to know the current day from the date picker, to speed up his decision making.

<ThemedImage
  light={datePickerBehaviourDateBoundingBoxCurrentDay}
  dark={datePickerBehaviourDateBoundingBoxCurrentDayDark}
  alt=""
/>

#### First and Last Date

First Date and Last Date are properties only available for Date Bounding Box component with selected state.

It should be used when a date range is indicated, to keep visual consistency between the Selected and In Range states of the Date Bounding Box.

<ThemedImage
  light={datePickerBehaviourDateBoundingBoxFirstAndLastDate}
  dark={datePickerBehaviourDateBoundingBoxFirstAndLastDateDark}
  alt=""
/>

### Header Menu

#### Year Calendar

By default, Year Calendar is not visible (Off state). When activated, it allows the user to select the targeted year efficiently.

States, similar to the Button component are proposed to cover every use case.

<ThemedImage
  light={datePickerBehaviourHeaderMenuYearCalendar}
  dark={datePickerBehaviourHeaderMenuYearCalendarDark}
  alt=""
/>

## Usage Guidelines

Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts.

### Never without my Date Input

- **Don’t**: suppress the date input field
- **Do**: always allow users to type the date

<ThemedImage
  light={datePickerUsageGuidelinesNeverWithoutMyDateInput}
  dark={datePickerUsageGuidelinesNeverWithoutMyDateInputDark}
  alt=""
/>

### A good Date Input is a personalized one

- **Don’t**: only use pre-filled date input provided by Quantum
- **Do**: adapt the input field to the localisation or the need of your user

<ThemedImage
  light={datePickerUsageGuidelinesAGoodDateInputIsAPersonalizedOne}
  dark={datePickerUsageGuidelinesAGoodDateInputIsAPersonalizedOneDark}
  alt=""
/>

### Drag selection behavior

- **Don’t**: only use click option to select a date range
- **Do**: propose a drag selection to adapt to user ease

<ThemedImage
  light={datePickerUsageGuidelinesDragSelectionBehavior}
  dark={datePickerUsageGuidelinesDragSelectionBehaviorDark}
  alt=""
/>

### Date Input for a Mobile usage

- **Don’t**: use date picker as a push
- **Do**: use date picker as a modal

<ThemedImage
  light={datePickerUsageGuidelinesDateInputForAMobileUsage}
  dark={datePickerUsageGuidelinesDateInputForAMobileUsageDark}
  alt=""
/>

### What about the reset feature

- **Don’t**: prevent the user's right to error
- **Do**: express the user’s right to error by displaying the Footer
  or with click-to-cancel mechanism

<ThemedImage
  light={datePickerUsageGuidelinesWhatAboutTheResetFeature}
  dark={datePickerUsageGuidelinesWhatAboutTheResetFeatureDark}
  alt=""
/>

### Uses of disable on days

- **Don’t**: limit yourself to using the default calendar
- **Do**: use date picker by adapting the days of unavailability to it’s context

<ThemedImage
  light={datePickerUsageGuidelinesUsesOfDisableOnDays}
  dark={datePickerUsageGuidelinesUsesOfDisableOnDaysDark}
  alt=""
/>

## Showcase

Showcase of a component - like a usage demonstration - help to make the complexity of a component more understandable, via the presentation of a concrete use by a hypothetical end user.

### Date Picker demonstration

**Hypothetical goal**

Select your travel dates - March 12, 2025 to April 5, 2025

**Steps**

- Use Range Date Picker
- Change years
- Change months
- Change days

<ThemedImage
  light={datePickerShowcase0}
  dark={datePickerShowcase0Dark}
  alt=""
/>

1. Open the Range Date Picker by clicking on the Date Input & open the Start date’s Year Picker by clicking on the arrow.

<ThemedImage
  light={datePickerShowcase1}
  dark={datePickerShowcase1Dark}
  alt=""
/>

2. Select the year & select the month within Header Menu by clicking on the chevron.

<ThemedImage
  light={datePickerShowcase2}
  dark={datePickerShowcase2Dark}
  alt=""
/>

3. Select the day within Calendar View & repeat the process for the End date.

<ThemedImage
  light={datePickerShowcase3}
  dark={datePickerShowcase3Dark}
  alt=""
/>

4. Enjoy your filled Range Date Picker.

<ThemedImage
  light={datePickerShowcase4}
  dark={datePickerShowcase4Dark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=17017-416805&t=kOWgyuqnVCEtliGV-4)



# Dropdown Multiselect

<ThemedImage
  light={dropdownMultiselect}
  dark={dropdownMultiselectDark}
  alt=""
/>

## Overview

Dropdown Multiselect allow users to select multiple items from a list of predefined items in a dropdown menu. Items are displayed as checkbox items to make the user understand the multiselection capability.

### Usage

When to use:

- Users need to select items from a long list of items.
- The values of the option list are secondary information and do not need to be displayed right away.

When not to use:

- Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [toggle switch](/docs/components/toggle-switch) control instead.
- You want the user to select one entry only. In this case, use the [text input](/docs/components/text-input) or [combo box](/docs/components/combo-box) instead.

### Sources and references

- [Combo box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Fiori

## Anatomy

This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes.

Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants.

<ThemedImage
  light={dropdownMultiselectAnatomy}
  dark={dropdownMultiselectAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Component: Dropdown multiselect

| Property       | Values                   | Default |
| -------------- | ------------------------ | ------- |
| **size**       | small / medium / large   | Medium  |
| **state**      | default / hover / filled | Default |
| **disabled**   | false / true             | False   |
| **error**      | false / true             | False   |
| **\*isOpen**   | false / true             | False   |
| **searchable** | false / true             | False   |
| **placement**  | bottom / top             | False   |

#### Composition

This component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

##### ❖ Sub-component: Text input

##### ❖ Sub-component: Dropdown menu

## Behaviour

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

### Sizes

Dropdown multiselects are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page.

For example, if you are using a medium size dropdown multiselect, also use the same size text inputs, buttons, and so on.

<ThemedImage
  light={dropdownMultiselectBehaviourSizes}
  dark={dropdownMultiselectBehaviourSizesDark}
  alt=""
/>

### Filterable input

When the dropdown menu gets longer than 10-20 items, a searchable input can allow a user to search items easier through a large list of choices instead of scrolling down.

<ThemedImage
  light={dropdownMultiselectBehaviourFilterableInput}
  dark={dropdownMultiselectBehaviourFilterableInputDark}
  alt=""
/>

### Autosuggest & autocomplete

The two types of selection suggestion should not be confused.

- Autosuggestion: filters through the list of items to give the user a smaller range of options to choose from.
- Autocomplete: when the input field puts forward a way to complete the sentence or the word.

<ThemedImage
  light={dropdownMultiselectBehaviourAutosuggestAutocomplete}
  dark={dropdownMultiselectBehaviourAutosuggestAutocompleteDark}
  alt=""
/>

### Completed input

When the user has selected an option, the dropdown multiselect should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state.

When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**.

To indicate the values in the field, we recommend using commas to separate items, or use removable tags to display the values.

[Find associated documentation on tags here](/docs/components/tag).

<ThemedImage
  light={dropdownMultiselectBehaviourCompletedInput}
  dark={dropdownMultiselectBehaviourCompletedInputDark}
  alt=""
/>

## Usage Guidelines

### Choosing radio buttons over dropdowns

- **Don’t**: use dropdowns for 5 options or less.
- **Do**: use radio buttons instead.

<ThemedImage
  light={dropdownMultiselectUsageGuidelinesChoosingRadioButtonsOverDropdowns}
  dark={dropdownMultiselectUsageGuidelinesChoosingRadioButtonsOverDropdownsDark}
  alt=""
/>

### Choosing text inputs over dropdowns

- **Don’t**: propose a dropdown if selecting an option takes more time than typing.
- **Do**: use text inputs (for example) instead.

<ThemedImage
  light={dropdownMultiselectUsageGuidelinesChoosingTextInputsOverDropdowns}
  dark={dropdownMultiselectUsageGuidelinesChoosingTextInputsOverDropdownsDark}
  alt=""
/>

### Avoid dropdowns for binary choices (On/Off - Yes/No - …)

- **Don’t**: make the user select between two binary and opposed options in a list.
- **Do**: use a toggle switch or a checkbox instead.

<ThemedImage
  light={dropdownMultiselectUsageGuidelinesAvoidDropdownsForBinaryChoices}
  dark={dropdownMultiselectUsageGuidelinesAvoidDropdownsForBinaryChoicesDark}
  alt=""
/>

### Avoid dropdowns for numeric choices

- **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …)
- **Do**: prefer using a text input (see below) to let them type in, or use a stepper. (coming soon)

<ThemedImage
  light={dropdownMultiselectUsageGuidelinesAvoidDropdownsForNumericChoices}
  dark={dropdownMultiselectUsageGuidelinesAvoidDropdownsForNumericChoicesDark}
  alt=""
/>

### Help the user for long lists of choices

- **Don’t**: give the user a too long, scrollable list of options to choose from without helping them.
- **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list.

<ThemedImage
  light={dropdownMultiselectUsageGuidelinesHelpTheUserForLongListsOfChoices}
  dark={dropdownMultiselectUsageGuidelinesHelpTheUserForLongListsOfChoicesDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284153&t=kOWgyuqnVCEtliGV-4)



# Dropdown Select

<ThemedImage light={dropdownSelect} dark={dropdownSelectDark} alt="" />

## Overview

Dropdown Selects allow the user to select a value from a list of choices with a single click.
Combined with searching capability or text entry in the field, dropdown selects become combo boxes.
[You can refer to the dedicated combo box documentation here.](/docs/components/combo-box)

### Usage

When to use:

- Users need to select a single item from a list of items.
- The values of the option list are secondary information and do not need to be displayed right away.

When not to use:

- Don’t use tooltips to display crucial information. This kind of information should always be accessible without any interaction from the users.
- To propose new actions: tooltips must always be informative only, and never actionable

## Anatomy

This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes.

Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants.

<ThemedImage
  light={dropdownSelectAnatomy}
  dark={dropdownSelectAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇❖ Component: Dropdown select

| Property      | Values                   | Default |
| ------------- | ------------------------ | ------- |
| **size**      | small / medium / large   | medium  |
| **state**     | default / hover / filled | default |
| **disabled**  | false / true             | false   |
| **error**     | false / true             | false   |
| **\*isOpen**  | false / true             | true    |
| **placement** | bottom / top             | bottom  |

#### Nested properties

This component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

##### ❖ Sub-component: Text input

##### ❖ Sub-component: Dropdown menu

## Behaviour

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

### Sizes

Dropdown selects are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page.

For example, if you are using a medium size dropdown select also use the same size text inputs, buttons, and so on.

<ThemedImage
  light={dropdownSelectBehaviourSizes}
  dark={dropdownSelectBehaviourSizesDark}
  alt=""
/>

### Completed input

When the user has selected an option, the dropdown should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state.

When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**.

<ThemedImage
  light={dropdownSelectBehaviourCompletedInput}
  dark={dropdownSelectBehaviourCompletedInputDark}
  alt=""
/>

### Using a combo box as a select

As referred previously in the documentation, you can use the dropdown select jointly with a text entry pattern to search or filter through the data in the dropdown menu.

This component is called a Combo box.
[Please refer to the dedicated documentation here.](/docs/components/combo-box)

<ThemedImage
  light={dropdownSelectBehaviourUsingAComboBoxAsASelect}
  dark={dropdownSelectBehaviourUsingAComboBoxAsASelectDark}
  alt=""
/>

## Usage Guidelines

### Choosing radio buttons over dropdowns

- **Don’t**: use dropdowns for 5 options or less.
- **Do**: use radio buttons instead.

<ThemedImage
  light={dropdownSelectUsageGuidelinesChoosingRadioButtonsOverDropdowns}
  dark={dropdownSelectUsageGuidelinesChoosingRadioButtonsOverDropdownsDark}
  alt=""
/>

### Choosing text inputs over dropdowns

- **Don’t**: propose a dropdown if selecting an option takes more time than typing.
- **Do**: use text inputs (for example) instead.

<ThemedImage
  light={dropdownSelectUsageGuidelinesChoosingTextInputsOverDropdowns}
  dark={dropdownSelectUsageGuidelinesChoosingTextInputsOverDropdownsDark}
  alt=""
/>

### Avoid dropdowns for binary choices (On/Off - Yes/No - …)

- **Don’t**: make the user select between two binary and opposed options in a list.
- **Do**: use a toggle switch or a checkbox instead.

<ThemedImage
  light={dropdownSelectUsageGuidelinesAvoidDropdownsForBinaryChoices}
  dark={dropdownSelectUsageGuidelinesAvoidDropdownsForBinaryChoicesDark}
  alt=""
/>

### Avoid dropdowns for numeric choices

- **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …)
- **Do**: prefer using a text input (see below) to let them type in, or use a stepper. (coming soon)

<ThemedImage
  light={dropdownSelectUsageGuidelinesAvoidDropdownsForNumericChoices}
  dark={dropdownSelectUsageGuidelinesAvoidDropdownsForNumericChoicesDark}
  alt=""
/>

### Help the user for long lists of choices

- **Don’t**: give the user a too long, scrollable list of options to choose from without helping them.
- **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list.

<ThemedImage
  light={dropdownSelectUsageGuidelinesHelpTheUserForLongListsOfChoices}
  dark={dropdownSelectUsageGuidelinesHelpTheUserForLongListsOfChoicesDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284145&t=kOWgyuqnVCEtliGV-4)



# Radio Button

<ThemedImage light={radioButton} dark={radioButtonDark} alt="" />

## Overview

Radio Buttons are used when you have a group of mutually exclusive choices and only one selection from the group is allowed.

### Usage

When to use:

- Forms of any kind.
- Settings: used to change from one setting to another.
- Selection in lists: used to choose a singular item within a list or table.

## Anatomy

<ThemedImage light={radioButtonAnatomy} dark={radioButtonAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Radio Button Group

| Property  | Values                 | Default |
| --------- | ---------------------- | ------- |
| **size**  | small / medium / large | medium  |
| **color** | primary / neutral      | primary |
| **items** | 2 to 10                | 3       |

#### ❖ Component: Radio Button

| Property         | Values                              | Default   |
| ---------------- | ----------------------------------- | --------- |
| **size**         | small / medium / large              | medium    |
| **color**        | primary / neutral                   | primary   |
| **state**        | default / hover / focused / pressed | default   |
| **error**        | true / false                        | false     |
| **disabled**     | true / false                        | false     |
| **checked**      | boolean                             | true      |
| **label**        | text                                | “Label”   |
| **\*hasCaption** | boolean                             | false     |
| **\*caption**    | text                                | “Caption” |

## Behaviour

### Sizes

Radio buttons are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium radio button is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the radio button, to increase the touch area.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={radioButtonBehaviourSizes}
  dark={radioButtonBehaviourSizesDark}
  alt=""
/>

### Emphasis

By default, radio buttons are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a radio button is required.

For visual components, like application panels, where a radio button shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen.

<ThemedImage
  light={radioButtonBehaviourEmphasis}
  dark={radioButtonBehaviourEmphasisDark}
  alt=""
/>

### Error

Radio buttons can also have an error state to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid.

<ThemedImage
  light={radioButtonBehaviourError}
  dark={radioButtonBehaviourErrorDark}
  alt=""
/>

### Text overflow

When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this:

- Set ‘**Label Base**’ text layer to fill container (horizontally).
- Set ‘**input-and-label**’ layer to fill container (horizontally).
- Set ‘**Base - Radio Button**’ layer to fill container (horizontally).
- Set ‘**Radio Button**’ layer to fill container (horizontally).

<ThemedImage
  light={radioButtonBehaviourTextOverflow}
  dark={radioButtonBehaviourTextOverflowDark}
  alt=""
/>

### Internationalization

For RTL (right-to-left) languages, the layout of the radio button is mirrored. The radio button input is placed on the right side of the text.

To build your own (BYO) version of this, either detach the **Radio Button** component or use the **Radio Button Input** component with the correct font scale and spacing as seen in the LTR version.

<ThemedImage
  light={radioButtonBehaviourInternationalization}
  dark={radioButtonBehaviourInternationalizationDark}
  alt=""
/>

## Usage Guidelines

### Use radio buttons for mutually exclusive options

- **Don’t**: use radio buttons if a user needs to select as many options as desired (or none).
- **Do**: use checkbox groups if the selection only requires a single option from a list of mutually exclusive options.

<ThemedImage
  light={radioButtonUsageGuidelinesUseRadioButtonsForMutuallyExclusiveOptions}
  dark={
    radioButtonUsageGuidelinesUseRadioButtonsForMutuallyExclusiveOptionsDark
  }
  alt=""
/>

### When to choose a radio button over a switch

- **Don’t**: use a radio button to communicate activation (e.g. on/off states) as they can have an error state and this could confuse users about the action they’re about to take.
- **Do**: use a radio button for communicating selection of mutually exclusive options.

<ThemedImage
  light={radioButtonUsageGuidelinesWhenToChooseARadioButtonOverASwitch}
  dark={radioButtonUsageGuidelinesWhenToChooseARadioButtonOverASwitchDark}
  alt=""
/>

### Label groups of related radio buttons

- **Don’t**: expect the users to understand a group of radio buttons, if they are not provided with a header or caption text.
- **Do**: provide a label with your radio buttons to describe what the list of options represents and guides the users in what to do. Especially for those using a screen reader.

<ThemedImage
  light={radioButtonUsageGuidelinesLabelGroupsOfRelatedRadioButtons}
  dark={radioButtonUsageGuidelinesLabelGroupsOfRelatedRadioButtonsDark}
  alt=""
/>

### Text wrapping

- **Don’t**: vertically centre wrapped text with the radio button.
- **Do**: let the text wrap beneath the radio button so the control and the label are top aligned.

<ThemedImage
  light={radioButtonUsageGuidelinesTextWrapping}
  dark={radioButtonUsageGuidelinesTextWrappingDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284113&t=kOWgyuqnVCEtliGV-4)



# Slider

<ThemedImage light={slider} dark={sliderDark} alt="" />

## Overview

Sliders are form elements with which users can set a value by dragging a cursor along a bar. It uses a knob or lever moved horizontally to control a variable, such as volume on a radio or brightness on a screen.

### Usage

When to use:

- When adjusting settings contained in a range
- When selecting a value from a predefined range
- When it’s possible to have a real-time feedback by dragging the handle
- When the specific value does not matter to the user, but an approximate value is good enough.

### Sources

- [Slider Design: Rules of Thumb](https://www.nngroup.com/articles/gui-slider-controls/) by Nielsen Norman Group
- [Slider Components overview](https://material.angular.dev/components/slider/overview) by Material Angular

## Anatomy

This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes.

Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants.

<ThemedImage light={sliderAnatomy} dark={sliderAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇◇◇❖ Legend Mark

| Property         | Values                 | Default |
| ---------------- | ---------------------- | ------- |
| **size**         | small / medium / large | medium  |
| **priority**     | main / secondary       | main    |
| **text**         | true / false           | true    |
| **textPosition** | top / bottom / none    | top     |
| **color**        | primary / neutral      | primary |
| **active**       | true / false           | false   |
| **value**        | text                   | “0”     |
| **tick**         | true / false           | true    |

#### ◇◇◇❖ Legend

| Property         | Values                 | Default |
| ---------------- | ---------------------- | ------- |
| **size**         | small / medium / large | medium  |
| **color**        | primary / neutral      | primary |
| **textPosition** | top / bottom / none    | top     |
| **tick**         | true / false           | true    |

#### ◇◇❖ Slider

| Property       | Values                                         | Default   |
| -------------- | ---------------------------------------------- | --------- |
| **size**       | small / medium / large                         | medium    |
| **color**      | primary / neutral                              | primary   |
| **state**      | default / hover / focused / pressed / disabled | default   |
| **two handle** | true / false                                   | false     |
| **tick**       | true / false                                   | false     |
| **hasTitle**   | true / false                                   | true      |
| **title**      | text                                           | “label”   |
| **hasCaption** | true / false                                   | true      |
| **caption**    | text                                           | “caption” |
| **showValue**  | true / false                                   | true      |
| **value**      | text                                           | “value”   |

#### ◇❖ Sub-component: Range Slider

| Property           | Values                                                     | Default |
| ------------------ | ---------------------------------------------------------- | ------- |
| **size**           | small / medium / large                                     | medium  |
| **color**          | primary / neutral                                          | primary |
| **legendPosition** | top / bottom / none                                        | bottom  |
| **start**          | 0% / 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90%   | 10%     |
| **length**         | 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90% / 100% | 60%     |

#### ◇❖ Sub-component: One Handle Slider

| Property           | Values                                                          | Default |
| ------------------ | --------------------------------------------------------------- | ------- |
| **size**           | small / medium / large                                          | medium  |
| **color**          | primary / neutral                                               | primary |
| **legendPosition** | top / bottom / none                                             | bottom  |
| **start**          | center / left                                                   | left    |
| **length**         | 0% / 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90% / 100% | 40%     |
| **direction**      | left / right / none                                             | right   |

## Behaviour

### One & two handles

The slider can be used with one or two handles. Thus, it can be used to select a value by dragging a handle along the axis or to define a range with the two-handled one.

<ThemedImage
  light={sliderBehaviourOneTwoHandles}
  dark={sliderBehaviourOneTwoHandlesDark}
  alt=""
/>

### Sizes

Sliders are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

<ThemedImage
  light={sliderBehaviourSizes}
  dark={sliderBehaviourSizesDark}
  alt=""
/>

### State

By default, the slider is in Default state.
The Hover state provides tooltips to display the value selected thanks to the handle.

<ThemedImage
  light={sliderBehaviourState}
  dark={sliderBehaviourStateDark}
  alt=""
/>

### Steps

The component has a wide variety of positions. By choosing a start and end value you can adapt it to most situations.

The slider offers three behaviors:

- start at left, at zero, to the right for a linear selection
- start at the center, to the right or left for a positive or negative selection (for example.)
- a range for more flexibility in the choice of values

<ThemedImage
  light={sliderBehaviourSteps}
  dark={sliderBehaviourStepsDark}
  alt=""
/>

### Colour

By default, sliders are emphasized (primary theme). Providing a visual prominence.

For visual components, like application panels, where colour shouldn't be a standout element, choose the neutral theme to de-emphasize its focus on the screen.

<ThemedImage
  light={sliderBehaviourColour}
  dark={sliderBehaviourColourDark}
  alt=""
/>

## Usage Guidelines

### Use slider for imprecise or pre-determined ranges

- **Don’t**: use slider for large (e.g. 1-1000) or small (e.g. 1-3) ranges
- **Do**: use slider for medium range

<ThemedImage
  light={sliderUsageGuidelinesUseSliderForImpreciseOrPreDeterminedRanges}
  dark={sliderUsageGuidelinesUseSliderForImpreciseOrPreDeterminedRangesDark}
  alt=""
/>

### Use slider without tick for imprecise range

- **Don’t**: use tick when the steps looks approximative
- **Do**: use slider without tick and give contextual labels

<ThemedImage
  light={sliderUsageGuidelinesUseSliderWithoutTickForImpreciseRange}
  dark={sliderUsageGuidelinesUseSliderWithoutTickForImpreciseRangeDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284113&t=kOWgyuqnVCEtliGV-4)



# Text Area

<ThemedImage light={textArea} dark={textAreaDark} alt="" />

## Overview

A text area lets a user input a longer amount of text than a standard text field. It can include all of the standard validation options supported by the text field component.

### Usage

When to use:

- Use the text area if you want users to enter multiple lines of text.

When not to use:

- Users need to enter a single line of text. For this we recommend using the text input instead.

## Anatomy

<ThemedImage light={textAreaAnatomy} dark={textAreaAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Text Area

| Property        | Values                              | Default       |
| --------------- | ----------------------------------- | ------------- |
| **size**        | small / medium / large              | medium        |
| **state**       | default / hover / active / filled   | default       |
| **severity**    | default / success / warning / error | default       |
| **disabled**    | false / true                        | false         |
| **hasLabel**    | boolean                             | true          |
| **label**       | text                                | “Label”       |
| **required**    | boolean                             | true          |
| **charCounter** | boolean                             | true          |
| **placeholder** | text                                | “Placeholder” |
| **hasCaption**  | boolean                             | true          |
| **caption**     | text                                | “Caption”     |
| **resize**      | boolean                             | true          |
| **scrollable**  | boolean                             | true          |
| **successIcon** | instance swap                       | check_circle  |
| **warningIcon** | instance swap                       | warning       |
| **errorIcon**   | instance swap                       | error         |

## Behaviour

### Minimum height

Text areas are ideal for long sentences or paragraphs, and should comfortably accommodate large amounts of text.

They should have a minimum height of 80px (medium) or 64px (small) on a desktop and 96px (large) on mobile (when the height of the text area is a defined number).

<ThemedImage
  light={textAreaBehaviourMinimumHeight}
  dark={textAreaBehaviourMinimumHeightDark}
  alt=""
/>

### Overflow

When typing into a text area and reaching the end of the field on a fixed-height text area, the cursor should continue to follow the text as the user types, while the rest of the text above overflows through the top of the field.

Note: in Figma to reflect the active typing behaviour, you can change the text alignment to **align bottom** as opposed to align top.

When the field loses focus, text should overflow through the bottom of the text area, showing the beginning of the text.

<ThemedImage
  light={textAreaBehaviourOverflow}
  dark={textAreaBehaviourOverflowDark}
  alt=""
/>

### Caption text overflow

When the caption text is too long for the available horizontal space, it wraps to form another line.

<ThemedImage
  light={textAreaBehaviourCaptionTextOverflow}
  dark={textAreaBehaviourCaptionTextOverflowDark}
  alt=""
/>

### Character count

Text areas can display a character count indicator when the length of the text entry needs to be kept under a predefined value. Character count indicators can be used in conjunction with other indicators (e.g., validation icon, “optional” or “required” indicators) when necessary.

We have intentionally left this specific error state out of our design, as it can be reflected in many ways and this component is flexible enough to customise it how you need it.

<ThemedImage
  light={textAreaBehaviourCharacterCount}
  dark={textAreaBehaviourCharacterCountDark}
  alt=""
/>

### Drag icon

Text areas can either be a fixed size or can be resizable with a drag icon in the bottom right corner. The drag icon should be hidden if the fixed variant is turned on, or if the text area should not be resizable.

<ThemedImage
  light={textAreaBehaviourDragIcon}
  dark={textAreaBehaviourDragIconDark}
  alt=""
/>

### Caption text (description or error message)

A text area can have caption text below the field to give extra context or instruction about what a user should input in the field. The caption text area has two options: a description and an error message.

The description communicates a hint or helpful information, such as specific requirements for correctly filling out the field.

The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input.

<ThemedImage
  light={textAreaBehaviourCaptionText}
  dark={textAreaBehaviourCaptionTextDark}
  alt=""
/>

## Usage Guidelines

### Use captions instead of placeholder text

- **Don’t**: put important instructions as placeholder text, otherwise that text will no longer be viewable when the user begins typing.
- **Do**: use the caption text to convey requirements or to show any formatting examples that would help user comprehension.

<ThemedImage
  light={textAreaUsageGuidelinesUseCaptionsInsteadOfPlaceholderText}
  dark={textAreaUsageGuidelinesUseCaptionsInsteadOfPlaceholderTextDark}
  alt=""
/>

### Switch caption text with error text

- **Don’t**: use the same caption text when presenting an error. Use the error text as an opportunity to help the user understand why something is incorrect.
- **Do**: replace the caption text with error text. Then once the error is resolved, the help text description reappears below the text area.

<ThemedImage
  light={textAreaUsageGuidelinesSwitchCaptionTextWithErrorText}
  dark={textAreaUsageGuidelinesSwitchCaptionTextWithErrorTextDark}
  alt=""
/>

### Write error text that shows a solution

- **Don’t**: state an error and then leave the user guessing why their value is incorrect.
- **Do**: use a helpful tone to convey a hint or tip to resolve the error, guiding them to understand what needs to go in the missing field.

<ThemedImage
  light={textAreaUsageGuidelinesWriteErrorTextThatShowsASolution}
  dark={textAreaUsageGuidelinesWriteErrorTextThatShowsASolutionDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284137&t=kOWgyuqnVCEtliGV-4)



# Text Input

<ThemedImage light={textInput} dark={textInputDark} alt="" />

## Overview

Text Inputs are box-shaped input fields that helps the user enter data to communicate to the machine, a system or a product. Various options exist in the Thales Design System and are presented in this documentation.

## Anatomy

Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please refer yourself to the properties table at the end of this section.

<ThemedImage light={textInputAnatomy} dark={textInputAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Text Input

| Property         | Values                              | Default       |
| ---------------- | ----------------------------------- | ------------- |
| **size**         | small / medium / large              | medium        |
| **state**        | default / hover / active / filled   | default       |
| **severity**     | default / success / warning / error | default       |
| **disabled**     | false / true                        | false         |
| **hasLabel**     | boolean                             | true          |
| **label**        | text                                | “Label”       |
| **required**     | boolean                             | true          |
| **hasLeftIcon**  | boolean                             | true          |
| **leftIcon**     | instance swap                       | person        |
| **placeholder**  | text                                | “Placeholder” |
| **hasRightIcon** | boolean                             | true          |
| **rightIcon**    | instance swap                       | expand_more   |
| **successIcon**  | instance swap                       | check_circle  |
| **warningIcon**  | instance swap                       | warning       |
| **errorIcon**    | instance swap                       | error         |
| **hasCaption**   | boolean                             | true          |
| **caption**      | text                                | “Caption”     |

## Behaviour

### Minimum width

To ensure that small text fields are easily readable and touchable on screen devices, we recommend a **minimum width of 1.5x the height** of the button. This means 48px (small), 60px (medium) and 72px (large)

<ThemedImage
  light={textInputBehaviourMinimumWidth}
  dark={textInputBehaviourMinimumWidthDark}
  alt=""
/>

### Label usage

Text inputs can be used either with a label on top of the field, or inside as a placeholder.
If you use the second option, make sure your label is explicit enough for the user to understand the data they should enter.
You can also use icons to help guide the user.



### Required and optional options

Depending on your forms structure, you might need to present “Required” or “Optional”.
We recommend using the dedicated asterisk for the labelled input, and the caption for the placeholder label option.



### Use required and optional correctly

In a complete form, you will always have required and optional fields.
To decrease cognitive load, **always indicate the less frequent option** and mark them.
For instance, if most of the fields are optional, only mark the required with an asterisk. If most of the fields are required, only mark the few optional ones with “(optional)” in the label.



### Validation and error states

To help guide the user in the completion of the form, you can use the embedded validation states. Available today are:

- Success
- Warning
- Error
  The semantic text temporarily replaces the help text underneath the text input, as the language should be more specific to how to user can resolve the error.



### Icon usage

The icon placeholders can help the user understand the expected input even more.
You should use left **OR** right icons to illustrate the label/placeholder. Using both icons is a unique use case and is only reserved for the following use cases:

- Validation
- Dropdown arrow button

<ThemedImage
  light={textInputBehaviourIconUsage}
  dark={textInputBehaviourIconUsageDark}
  alt=""
/>

## Usage Guidelines

### Choose the best type in your context

- **Don’t**: mix top label and placeholder label in the same form.
- **Do**: make the one choice that fit the most your product.

<ThemedImage
  light={textInputUsageGuidelinesChooseTheBestTypeInYourContext}
  dark={textInputUsageGuidelinesChooseTheBestTypeInYourContextDark}
  alt=""
/>

### Keep labels short and precise

- **Don’t**: describe too much within the label.
- **Do**: stay clear, precise and explicit.

<ThemedImage
  light={textInputUsageGuidelinesKeepLabelsShortAndPrecise}
  dark={textInputUsageGuidelinesKeepLabelsShortAndPreciseDark}
  alt=""
/>

### Adapt length and related groups relatively to the data

- **Don’t**: employ same length for very different data input sizes.
- **Do**: adapt and create related groups of data inputs.

<ThemedImage
  light={textInputUsageGuidelinesAdaptLengthAndRelatedGroupsRelativelyToTheData}
  dark={
    textInputUsageGuidelinesAdaptLengthAndRelatedGroupsRelativelyToTheDataDark
  }
  alt=""
/>

### Use sentence case for everything

- **Don’t**: Mix or use different types of cases than sentence case, exception is made for acronyms.
- **Do**: use sentence case for everything.

<ThemedImage
  light={textInputUsageGuidelinesUseSentenceCaseForEverything}
  dark={textInputUsageGuidelinesUseSentenceCaseForEverythingDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284129&t=kOWgyuqnVCEtliGV-4)



# Toggle Switch

<ThemedImage light={toggleSwitch} dark={toggleSwitchDark} alt="" />

## Overview

Toggle Switch are On/Off switches. They are meant to ask the user to choose between two mutually opposed options, and always have a default value, whether it’s off or on.

Toggles, and in that case switches, always have a direct impact and provide immediate results.

## Anatomy

<ThemedImage
  light={toggleSwitchAnatomy}
  dark={toggleSwitchAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Toggle switch

| Property          | Values                      | Default |
| ----------------- | --------------------------- | ------- |
| **size**          | small / medium / large      | medium  |
| **color**         | primary / neutral           | primary |
| **state**         | default / pressed / focused | default |
| **checked**       | false / true                | false   |
| **disabled**      | false / true                | false   |
| **labelPosition** | left / right                | right   |
| **hasLabel**      | boolean                     | true    |
| **labelOn**       | text                        | “Label” |
| **labelOff**      | text                        | “Label” |
| **displayIcon**   | boolean                     | true    |
| **iconOff**       | instance swap               | check   |
| **iconOn**        | instance swap               | check   |

## Behaviour

### Sizes

Switches are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium switch is used typically for desktop/tablet devices. But for mobile devices, it is possible that you need to upscale the switch, to increase the touch area.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={toggleSwitchBehaviourSizes}
  dark={toggleSwitchBehaviourSizesDark}
  alt=""
/>

### Switch activation

The “activated” parameter allows you to easily switch from off to on and the other way around with a simple press of a button.

<ThemedImage
  light={toggleSwitchBehaviourSwitchActivation}
  dark={toggleSwitchBehaviourSwitchActivationDark}
  alt=""
/>

### Label

For flexibility purposes, you can choose to integrate a switch without label.

Therefore, the toggle labels should describe what the control will do when the switch is on and a toggle should always indicate to the user the impact.

<ThemedImage
  light={toggleSwitchBehaviourLabel}
  dark={toggleSwitchBehaviourLabelDark}
  alt=""
/>

### Emphasis

By default, switches are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a switch is required.

For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen.

<ThemedImage
  light={toggleSwitchBehaviourEmphasis}
  dark={toggleSwitchBehaviourEmphasisDark}
  alt=""
/>

### Resizing to fit

Sometimes, you will need to change the base auto-layout model from “Packed” to “Space between” in order to make your component horizontally fit its container.
You can change this setting directly at the top level of the component in the auto-layout panel

<ThemedImage
  light={toggleSwitchBehaviourResizingToFit}
  dark={toggleSwitchBehaviourResizingToFitDark}
  alt=""
/>

### Text overflow

When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this:

1. Set ‘**Switch label**’ text layer to fill container (horizontally).
2. Resize the main component to the right width.

<ThemedImage
  light={toggleSwitchBehaviourTextOverflow}
  dark={toggleSwitchBehaviourTextOverflowDark}
  alt=""
/>

## Usage Guidelines

### Deliver immediate results

- **Don’t**: ask the user to save the changes or apply changes when switching a toggle.
- **Do**: deliver immediate effect on your interfaces.

<ThemedImage
  light={toggleSwitchUsageGuidelinesDeliverImmediateResults}
  dark={toggleSwitchUsageGuidelinesDeliverImmediateResultsDark}
  alt=""
/>

### Use concise and clear labels

- **Don’t**: write labels like “Do you want to see the next flights?”
- **Do**: write “Show next flights” instead

<ThemedImage
  light={toggleSwitchUsageGuidelinesUseConciseAndClearLabels}
  dark={toggleSwitchUsageGuidelinesUseConciseAndClearLabelsDark}
  alt=""
/>

### Choosing a switch over a checkbox

- **Don’t**: use a checkbox to ask the user to choose between two exclusive and mutually opposed options, implying an on/off state.
- **Do**: use a toggle switch instead

<ThemedImage
  light={toggleSwitchUsageGuidelinesChoosingASwitchOverACheckbox}
  dark={toggleSwitchUsageGuidelinesChoosingASwitchOverACheckboxDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284121&t=kOWgyuqnVCEtliGV-4)



# Breadcrumb

<ThemedImage light={breadcrumb} dark={breadcrumbDark} alt="" />

## Overview

A breadcrumb, or breadcrumb trail is a graphical control element frequently used as a navigational aid in user interfaces and on web pages. It allows users to keep track and maintain awareness of their locations within programs, documents, or websites.

The term is a reference to the trail of bread crumbs left by Hansel and Gretel in the German fairy tale of the same name. (Wikipedia)

### Sources and references

- [Breadcrumbs: 11 Design Guidelines for Desktop and Mobile](https://www.nngroup.com/articles/breadcrumbs/) - Nielsen Norman Group
- [When You Should Use a Breadcrumb Navigation](https://uxmovement.com/navigation/when-you-should-use-a-breadcrumb-navigation/) - UX Movement

## Anatomy

<ThemedImage light={breadcrumbAnatomy} dark={breadcrumbAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Breadcrumbs

| Property         | Values                 | Default |
| ---------------- | ---------------------- | ------- |
| **size**         | small / medium / large | medium  |
| **color**        | primary / neutral      | primary |
| **\*itemNumber** | 2 to 5 and more        | 3       |
| **separator**    | > / /                  | >       |

#### ❖ Sub-component: Breadcrumb item

| Property      | Values                              | Default    |
| ------------- | ----------------------------------- | ---------- |
| **size**      | small / medium / large              | medium     |
| **color**     | primary / neutral                   | primary    |
| **\*state**   | default / focused / hover / pressed | default    |
| **active**    | false / true                        | false      |
| **\*hasIcon** | boolean                             | true       |
| **icon**      | swap instance                       | home       |
| **label**     | text                                | Breadcrumb |

## Behaviour

### Sizes

Breadcrumbs are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium breadcrumbs are used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the component, to increase the touch area.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={breadcrumbBehaviourSizes}
  dark={breadcrumbBehaviourSizesDark}
  alt=""
/>

### Colour emphasis

By default, breadcrumbs are not emphasized (primary theme). Providing a visual prominence that is optimal for a navigation system.

The neutral theme is more appropriate when you need to de-prioritize its focus on the screen.

<ThemedImage
  light={breadcrumbBehaviourColourEmphasis}
  dark={breadcrumbBehaviourColourEmphasisDark}
  alt=""
/>

### Separator options

The breadcrumbs have 2 options of separators which are “/” and “>”. Prefer using the chevron as your separator because of the visual representation that indicates movement, and emphasize more on the content’s cascading structure.

<ThemedImage
  light={breadcrumbBehaviourSeparatorOptions}
  dark={breadcrumbBehaviourSeparatorOptionsDark}
  alt=""
/>

### Long breadcrumbs management

When you have a long breadcrumb trail, you should consider improving readability by shrinking the breadcrumb down to 5 items.

To make this happen, you can create a “…” item - already included in the “5 and more” item option - and insert the hidden items in a dropdown menu.

<ThemedImage
  light={breadcrumbBehaviourLongBreadcrumbsManagement}
  dark={breadcrumbBehaviourLongBreadcrumbsManagementDark}
  alt=""
/>

### Icons option

By default, the home link has an included icon. You can also add icons on every label, but need to use them properly (cf. usage guidelines on this)

<ThemedImage
  light={breadcrumbBehaviourIconsOption}
  dark={breadcrumbBehaviourIconsOptionDark}
  alt=""
/>

## Usage Guidelines

### The first item must be the home page

- **Don’t**: put a first item that is not the starting point.
- **Do**: display the starting point as first item to recognize hierarchy.

<ThemedImage
  light={breadcrumbUsageGuidelinesTheFirstItemMustBeTheHomePage}
  dark={breadcrumbUsageGuidelinesTheFirstItemMustBeTheHomePageDark}
  alt=""
/>

### The last item is where the user is, so it should not be clickable

- **Don’t**: let the user click the last item (current location). This will prevent an unnecessary page refresh.
- **Do**: keep it recognizable, but different from the others.

<ThemedImage
  light={
    breadcrumbUsageGuidelinesTheLastItemIsWhereTheUserIsSoItShouldNotBeClickable
  }
  dark={
    breadcrumbUsageGuidelinesTheLastItemIsWhereTheUserIsSoItShouldNotBeClickableDark
  }
  alt=""
/>

### Keep your labels short to avoid wrapping issues

- **Don’t**: clutter your breadcrumbs with too long page titles. If you see your breadcrumbs have wrapping issues, this might be the chance to consider cleaning up your page names.
- **Do**: keep it short and efficient.

<ThemedImage
  light={breadcrumbUsageGuidelinesKeepYourLabelsShortToAvoidWrappingIssues}
  dark={breadcrumbUsageGuidelinesKeepYourLabelsShortToAvoidWrappingIssuesDark}
  alt=""
/>

### Icons are not page links.

- **Don’t**: use icons only as links in your breadcrumbs.
- **Do**: always have a label when using icons to ensure readability and understandability.

<ThemedImage
  light={breadcrumbUsageGuidelinesIconsAreNotPageLinks}
  dark={breadcrumbUsageGuidelinesIconsAreNotPageLinksDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284105&t=kOWgyuqnVCEtliGV-4)



# Rail

<ThemedImage light={rail} dark={railDark} alt="" />

## Overview

Navigation rails increase the level of product’s discoverability by letting the user know exactly where they are in the product, and taking them to where they want to go quickly and effortlessly. It is often used as a first level of navigation.

### Usage

When to use:

- Navigating between unrelated destinations
- Your product has five or more top-level destinations (single-level)

For more information about layout and when/how to choose between a Navigation rail and a Navigation drawer, please visit the dedicated section in [Foundations / Grids & Layout](/docs/foundations/grids-layout).

## Anatomy

Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please visit the Customization page where it introduces you to the variants that define the make up of the **Navigation Rail**.

<ThemedImage light={railAnatomy} dark={railAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Rail

| Property        | Values                 | Default |
| --------------- | ---------------------- | ------- |
| **size**        | small / medium / large | medium  |
| **bottom menu** | true / false           | true    |

#### ❖ Sub-Component: Menu Item

| Property     | Values                                                                                                                                                       | Default     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **size**     | small / medium / large                                                                                                                                       | medium      |
| **state**    | default / hover / focused / active (ltr) / active (rtl) / active + hover (ltr) / active + hover / active + pressed (ltr) / active + pressed (rtl) / disabled | default     |
| **icon**     | swap instance                                                                                                                                                | train       |
| **hasLabel** | true / false                                                                                                                                                 | true        |
| **label**    | text                                                                                                                                                         | “menu item” |

#### ◇❖ Sub-Component: Menu Item List

| Property         | Values                 | Default |
| ---------------- | ---------------------- | ------- |
| **size**         | small / medium / large | medium  |
| **no. of items** | 1 to 8                 | 5       |

## Behaviour

### Icon and label

You can use the icons and labels option to ensure good reading to your end user. Labels will help the end user contextualize the icon.
When writing labels, always consider the length of your word. If the word is too long the end should be truncated with “…”

<ThemedImage
  light={railBehaviourIconAndLabel}
  dark={railBehaviourIconAndLabelDark}
  alt=""
/>

### Icon only

Even if it’s not recommended to use this pattern, you can use an icon only rail.
If you choose to do so, make sure to use icons that indicate explicitly the feature behind, and make sure you have the right alternative text for browser readers.

<ThemedImage
  light={railBehaviourIconOnly}
  dark={railBehaviourIconOnlyDark}
  alt=""
/>

## Usage Guidelines

### Navigation items

- **Don’t**: include navigation item names that are irrelevant or may seem redundant alongside other items
- **Do**: make information easier to find with navigation items names that are meaningful, concise and consistent.

<ThemedImage
  light={railUsageGuidelinesNavigationItems}
  dark={railUsageGuidelinesNavigationItemsDark}
  alt=""
/>

### Sentence case

- **Don’t**: use anything else, unless bespoke design decisions warrant a change.
- **Do**: use sentence case for menu items.

<ThemedImage
  light={railUsageGuidelinesSentenceCase}
  dark={railUsageGuidelinesSentenceCaseDark}
  alt=""
/>

### Icon and labels usage

- **Don’t**: alternate the usage of icon and text-only menu items in the same sections. Try to choose one consistent pattern for your navigation zones.
- **Do**: use icon and labeled items in a consistent fashion to keep a clear hierarchy.

<ThemedImage
  light={railUsageGuidelinesIconAndLabelsUsage}
  dark={railUsageGuidelinesIconAndLabelsUsageDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284081&t=kOWgyuqnVCEtliGV-4)



# Search

<ThemedImage light={search} dark={searchDark} alt="" />

## Overview

Search is a text input field specifically designed to help users browse and navigate around a platform.

### Sources and references

- [Best practices for search](https://www.uxbooth.com/articles/best-practices-for-search/) - UX Booth
- [Search](https://m2.material.io/design/navigation/search.html) - Material Design
- [ARIA Search Landmarks](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html) - W3C
- [Search Fields](https://developer.apple.com/design/human-interface-guidelines/search-fields) - Apple
- [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311) - UX Planet

## Anatomy

Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please refer yourself to the properties table at the end of this section.

<ThemedImage light={searchAnatomy} dark={searchAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇◇❖ Component: Search

| Property        | Values                                       | Default |
| --------------- | -------------------------------------------- | ------- |
| **size**        | small / medium / large                       | medium  |
| **state**       | default / hover / filled / active / disabled | default |
| **leftIcon**    | true / false                                 | false   |
| **showResults** | true / false                                 | false   |
| **button**      | none / iconButton / button                   | none    |

#### Composition

Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu), [Text Input](/docs/components/text-input) & [Button](/docs/components/button) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way.

##### ❖ Sub-component: Text input

##### ❖ Sub-component: Dropdown menu

##### ❖ Sub-component: Buttons

## Behaviour

### Manual search

Manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.

<ThemedImage
  light={searchBehaviourManualSearch}
  dark={searchBehaviourManualSearchDark}
  alt=""
/>

### Live search

Also known as “incremental search” or “search-as-you-type”, the live searching capability is triggered by each character that is entered/deleted by the user.

<ThemedImage
  light={searchBehaviourLiveSearch}
  dark={searchBehaviourLiveSearchDark}
  alt=""
/>

### Persistent search

Use persistent search when it is a primary focal point for your application. The persistent search is always available to users and typically used as a global search.

<ThemedImage
  light={searchBehaviourPersistentMatch}
  dark={searchBehaviourPersistentMatchDark}
  alt=""
/>

### Expandable search

Use expandable search when search is not the primary focus of your app. Expandable search displays a search icon in the toolbar, instead of an open search text box.

<ThemedImage
  light={searchBehaviourExpandableSearch}
  dark={searchBehaviourExpandableSearchDark}
  alt=""
/>

## Usage Guidelines

### Use effective autosuggest

- **Don’t**: mix all the results visually to avoid confusion from the users.
- **Do**: help users speed up the search process by keeping them on-task toward conversion.

<ThemedImage
  light={searchUsageGuidelinesUseEffectiveAutosuggest}
  dark={searchUsageGuidelinesUseEffectiveAutosuggestDark}
  alt=""
/>

### Don’t include a label

- **Don’t**: mix top label and placeholder label in the same form.
- **Do**: make the one choice that fit the most your product.

<ThemedImage
  light={searchUsageGuidelinesDonTIncludeALabel}
  dark={searchUsageGuidelinesDonTIncludeALabelDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284065&t=kOWgyuqnVCEtliGV-4)



# Stepper

<ThemedImage light={stepper} dark={stepperDark} alt="" />

## Overview

A stepper keeps users informed about their progress in a multi-step process by indicating what step they are on, what has been done and what is waiting to be completed.

### Usage

When to use:

- Users need to accomplish a larger goal through manageable steps that would otherwise be overwhelming to do it in one go.
- Users need to go through a sequence of logical and numbered steps with smaller goals.
- Users need to track the progress of a process (e.g. delivery, service, …).

When not to use:

- Users need to be informed of their current location during navigation, consider using [breadcrumbs](/docs/components/breadcrumb) instead.

## Anatomy

<ThemedImage light={stepperAnatomy} dark={stepperAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Stepper

| Property                      | Values                 | Default    |
| ----------------------------- | ---------------------- | ---------- |
| **size**                      | small / medium / large | medium     |
| **direction**                 | horizontal / vertical  | horizontal |
| **steps**                     | 3 / 4 / 5 / 6          | 3          |
| **style**                     | number / icon / dot    | number     |
| **caption**                   | true / false           | true       |
| **textPosition (horizontal)** | right / bottom         | right      |
| **content (vertical)**        | true / false           | false      |

#### ❖ Sub-Component: Step horizontal

| Property         | Values                                         | Default   |
| ---------------- | ---------------------------------------------- | --------- |
| **size**         | small / medium / large                         | medium    |
| **status**       | waiting / current / done / error               | waiting   |
| **state**        | default / hover / focused / pressed / disabled | default   |
| **style**        | number / icon / dot                            | number    |
| **textPosition** | bottom / right                                 | right     |
| **label**        | text                                           | “step”    |
| **showCaption**  | true / false                                   | true      |
| **caption**      | text                                           | “caption” |
| **track**        | true / false                                   | true      |

#### ❖ Sub-Component: Step vertical

| Property        | Values                                         | Default   |
| --------------- | ---------------------------------------------- | --------- |
| **size**        | small / medium / large                         | medium    |
| **status**      | waiting / current / done / error               | waiting   |
| **state**       | default / hover / focused / pressed / disabled | default   |
| **style**       | number / icon / dot                            | number    |
| **label**       | text                                           | “step”    |
| **showCaption** | true / false                                   | true      |
| **caption**     | text                                           | “caption” |
| **content**     | true / false                                   | true      |
| **track**       | true / false                                   | true      |

## Behaviour

### Direction

Steppers are available in two different directions depending of the space of the screen and the user’s needs.

For smaller devices, horizontal steppers can be implemented with a horizontal scroll. Or vertical steppers can be used with minimal adjustments required.

<ThemedImage
  light={stepperBehaviourDirection}
  dark={stepperBehaviourDirectionDark}
  alt=""
/>

### Sizes

Steppers are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

By default, the medium stepper is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the stepper, to increase the touch area.

For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html).

<ThemedImage
  light={stepperBehaviourSizes}
  dark={stepperBehaviourSizesDark}
  alt=""
/>

### Status

To keep the user engaged in different tasks, step status give an indication of where in the process they are, what has been done, and what are the next steps.

**Waiting**: This shows an upcoming step that isn’t completed yet by the user.

**Current**: This shows the step that the user is currently on.

**Done**: This shows a step the user has already completed.

**Error**: This shows a step the user has not finished

<ThemedImage
  light={stepperBehaviourStatus}
  dark={stepperBehaviourStatusDark}
  alt=""
/>

### Step styles

Depending of the goal of the stepper, different styles can be used :

**Number**: Indicating the step number, making it easier for the user to keep of where they are in a process. This is recommended when used to display a fixed linear process that requires information from the previous step.

**Icon**: Icons can be used to enhance the step’s goal, in addition to the label and the caption. This is recommended for use when the linear process can be navigated back and forth with no fixed direction.

**Dot**: A dot can be used to simplify the stepper for narrower screens, such as mobiles or a complex desktop design.

<ThemedImage
  light={stepperBehaviourStepStyles}
  dark={stepperBehaviourStepStylesDark}
  alt=""
/>

### Linear stepper

Linear steppers require users to complete tasks step-by-step in order to move to the next one. Users can only navigate forward, or backward to the adjacent steps.

<ThemedImage
  light={stepperBehaviourLinearStepper}
  dark={stepperBehaviourLinearStepperDark}
  alt=""
/>

### Non-linear stepper

Non-linear steppers allow users to complete any step in a random order. Users can also navigate to another non-adjacent step.

<ThemedImage
  light={stepperBehaviourNonLinearStepper}
  dark={stepperBehaviourNonLinearStepperDark}
  alt=""
/>

### Horizontal - Text position

Depending of the density of your screen, text position can be placed either at the left or the bottom of the indicator. For processes with many steps and a narrow screen, bottom text helps improving readability across steps.

<ThemedImage
  light={stepperBehaviourHorizontalTextPosition}
  dark={stepperBehaviourHorizontalTextPositionDark}
  alt=""
/>

### Vertical - Adding content

When using a horizontal stepper, content associated to the step can be added. To swap the default content with your own, follow these simple steps:

1. Create your composition in a frame and apply Auto layout to it.
2. Create a local component with this frame.
3. Drag-and-drop the local component from your assets panel while pressing CMD+OPT (CTRL+ALT for Windows) to swap the default content.
4. Make sure you apply the correct resizing constraints for the content area so that it hugs the next contents in the stepper.

<ThemedImage
  light={stepperBehaviourVerticalAddingContent}
  dark={stepperBehaviourVerticalAddingContentDark}
  alt=""
/>

### Vertical - Make the stepper fluid

By default, the vertical stepper has a fixed height with all steps set to “Hug contents”.

In order to make the vertical stepper fluid, non-current steps excepting the last one can be set to “Fill container”.

<ThemedImage
  light={stepperBehaviourVerticalMakeTheStepperFluid}
  dark={stepperBehaviourVerticalMakeTheStepperFluidDark}
  alt=""
/>

## Usage Guidelines

### Keep step labels short and concise

- **Don’t**: Use long names for steps
- **Do**: Use labels that clearly indicate the purpose of the step. You can also use the labels to enumerate the step, and use the caption as step label.

<ThemedImage
  light={stepperUsageGuidelinesKeepStepLabelsShortAndConcise}
  dark={stepperUsageGuidelinesKeepStepLabelsShortAndConciseDark}
  alt=""
/>

### Consistent use of nouns or verbs throughout all steps

- **Don’t**: Mix nouns and verbs
- **Do**: Use the same naming type through all steps

<ThemedImage
  light={stepperUsageGuidelinesConsistentUseOfNounsOrVerbsThroughoutAllSteps}
  dark={stepperUsageGuidelinesConsistentUseOfNounsOrVerbsThroughoutAllStepsDark}
  alt=""
/>

### Avoid using multiple steppers on one page

- **Don’t**: Use multiple steppers on one page.
- **Do**: Organize content by theme within one step to avoid decision fatigue.

<ThemedImage
  light={stepperUsageGuidelinesAvoidUsingMultipleSteppersOnOnePage}
  dark={stepperUsageGuidelinesAvoidUsingMultipleSteppersOnOnePageDark}
  alt=""
/>

### Use between 3 and 6 steps

- **Don’t**: Use the stepper for processes with fewer than 3 or more than 6 steps.
- **Do**: Simplify the process by organizing your content by theme or breaking up into multiple tasks.

<ThemedImage
  light={stepperUsageGuidelinesUseBetween3And6Steps}
  dark={stepperUsageGuidelinesUseBetween3And6StepsDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=16676-485553&t=kOWgyuqnVCEtliGV-4)



# Tabs

<ThemedImage light={tabs} dark={tabsDark} alt="" />

## Overview

Tabs organize content into multiple sections and allow users to navigate between them.
The content under tabs should be contextual to the page it sits within.

When to use tabs:

- Locally navigate between content at the same level of your navigation hierarchy.
- To alternate between views within the same context.

Want to learn more? [Jakob Nielsen describes how to use tabs - the right way](https://www.nngroup.com/articles/tabs-used-right/).

## Anatomy

Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please visit the Customization page where it introduces you to the variants that define the make up of the **Tabs**.

<ThemedImage light={tabsAnatomy} dark={tabsAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇❖ Component: Tabs

| Property           | Values                               | Default    |
| ------------------ | ------------------------------------ | ---------- |
| **size**           | small / medium                       | medium     |
| **items**          | 2 to 8                               | 8          |
| **fluid**          | false / true                         | false      |
| **fullHeight**     | false / true                         | false      |
| **\*iconOnly**     | false / true                         | false      |
| **\*iconPosition** | none / left / right / top / iconOnly | none       |
| **tabDirection**   | horizontal / vertical                | horizontal |
| **divider**        | false / true                         | true       |

#### Component: Tab Item

#### ❖ Sub-component: Tab Item

| Property           | Values                              | Default     |
| ------------------ | ----------------------------------- | ----------- |
| **size**           | small / medium                      | medium      |
| **state**          | default / hover / pressed / focused | default     |
| **active**         | true / false                        | true        |
| **disabled**       | true / false                        | true        |
| **\*hasLabel**     | boolean                             | true        |
| **label**          | text                                | “Item”      |
| **\*hasIcon**      | boolean                             | true        |
| **icon**           | instance swap                       | layers      |
| **\*hasLeftIcon**  | boolean                             | true        |
| **\*leftIcon**     | instance swap                       | settings    |
| **\*hasRightIcon** | boolean                             | true        |
| **\*rightIcon**    | instance swap                       | expand_more |

## Behaviour

### Sizes

Tabs exist with 2 different sizes, small and medium.

<ThemedImage light={tabsBehaviourSizes} dark={tabsBehaviourSizesDark} alt="" />

### States

A tab has several interactive states - Default, Hover, Focused, Pressed, Active, Active & Hover, Disabled.

<ThemedImage
  light={tabsBehaviourStates}
  dark={tabsBehaviourStatesDark}
  alt=""
/>

### Icons

Icons can be used in tab items, but should only be used when it is absolutely necessary.

Icons should not be used just as decoration. If the tab item does not have a visible label, it must still have a **tooltip** to disclose the label.

Icons in tabs can make information easier to find and scan. We recommend to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button. However, right icon can be set for right-to-left reading usages.

<ThemedImage light={tabsBehaviourIcons} dark={tabsBehaviourIconsDark} alt="" />

### Divider

By default, tabs have a divider that spans across all tab items. This style works as a way to anchor them to the page. These types of tabs are best used at the top of a page, as a top-level navigation.

Alternatively, tabs can be used without a divider. These should be used as sub-level navigation or for containers.

<ThemedImage
  light={tabsBehaviourDivider}
  dark={tabsBehaviourDividerDark}
  alt=""
/>

### Fixed tabs

#### Fluid fixed tabs (Container based)

Fixed tabs have equal width, which can be calculated either as:

- The width of the screen divided by the number of tabs
- The width of the widest tab label

When using fixed tabs, ensure they can all be seen on mobile, without truncating their text. Don’t use more than four fixed tabs at once.

<ThemedImage
  light={tabsBehaviourFixedTabsFluidFixedTabsContainerBased}
  dark={tabsBehaviourFixedTabsFluidFixedTabsContainerBasedDark}
  alt=""
/>

#### Clustered fixed tabs (Content based)

Clustered fixed tabs aren’t divided equally across the screen. The tabs can be centred, right-aligned, or left-aligned.

Clustered fixed tabs should be used in wide horizontal layouts, such as landscape mode on tablets or desktops.

<ThemedImage
  light={tabsBehaviourFixedTabsClusteredFixedTabsContentBased}
  dark={tabsBehaviourFixedTabsClusteredFixedTabsContentBasedDark}
  alt=""
/>

### Scrollable tabs

When a set of tabs cannot fit on the screen, use scrollable tabs.

Scrollable tabs can use longer text labels and a larger number of tabs. They are best used for browsing on touch interfaces.

<ThemedImage
  light={tabsBehaviourScrollableTabs0}
  dark={tabsBehaviourScrollableTabs0Dark}
  alt=""
/>



## Usage Guidelines

### Equal level of importance

- **Don’t**: use tabs for varying levels of importance.
- **Do**: use tabs for organizing content of equal importance.

<ThemedImage
  light={tabsUsageGuidelinesEqualLevelOfImportance}
  dark={tabsUsageGuidelinesEqualLevelOfImportanceDark}
  alt=""
/>

### Consistent icon usage

- **Don’t**: mix the use of icons in tabs, as navigation controls require a clear spacial relationship to one another.
- **Do**: use consistent and relevant icons for tabs to establish a clear visual balance and presence for each tab item.

<ThemedImage
  light={tabsUsageGuidelinesConsistentIconUsage}
  dark={tabsUsageGuidelinesConsistentIconUsageDark}
  alt=""
/>

### Avoid nesting of tabs

- **Don’t**: nest a tab within another tab.
- **Do**: use single-level tabs.

<ThemedImage
  light={tabsUsageGuidelinesAvoidNestingOfTabs}
  dark={tabsUsageGuidelinesAvoidNestingOfTabsDark}
  alt=""
/>

### Sentence case

- **Don’t**: use anything else, unless bespoke design decisions warrant a change.
- **Do**: use sentence case for tab items.

<ThemedImage
  light={tabsUsageGuidelinesSentenceCase}
  dark={tabsUsageGuidelinesSentenceCaseDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284057&t=kOWgyuqnVCEtliGV-4)



# Progress Bar

<ThemedImage light={progressBar} dark={progressBarDark} alt="" />

## Overview

A progress bar is a progress indicator, either determinate (indicating a percentage of progression) or indeterminate (indicating a state of loading).

### Usage

When to use:

- When managing action like download, upload, retrieval of data, …
- When the system is temporarily disabled, to block the screen
- When the processing takes more than a few seconds
- Generally, to provide feedback to the user about progression.

### Sources and references

- https://www.nngroup.com/articles/progress-indicators/

## Anatomy

<ThemedImage light={progressBarAnatomy} dark={progressBarAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Progress Bar

| Property          | Values                                                                    | Default             |
| ----------------- | ------------------------------------------------------------------------- | ------------------- |
| **variant**       | determinate / indeterminate                                               | determinate         |
| **size**          | small / medium / large                                                    | medium              |
| **color**         | primary / neutral                                                         | primary             |
| **state**         | loading / error / success                                                 | loading             |
| **\*animated**    | false / true                                                              | true                |
| **animation**     | none / load (determinate) / bounce (indeterminate) / loop (indeterminate) | load (determinate)  |
| **value**         | N/A / 1% / 17% / 34% / 67% / 100%                                         | N/A                 |
| **\*label+value** | boolean                                                                   | true                |
| **\*hasLabel**    | boolean                                                                   | true                |
| **\*label**       | text                                                                      | Downloading         |
| **showValue**     | boolean                                                                   | true                |
| **\*hasCaption**  | boolean                                                                   | true                |
| **\*caption**     | text                                                                      | Caption placeholder |

## Behaviour

### Determinate & Indeterminate

The progress bar comes in two different variants:

The determinate type, when progress can be calculated against a target (download, upload, know sizes, …)

The indeterminate type, when there is progress but the completion cannot be determined (connection to a server, retrieving unknown amount of data, …)

<ThemedImage
  light={progressBarBehaviourDeterminateIndeterminate}
  dark={progressBarBehaviourDeterminateIndeterminateDark}
  alt=""
/>

### Sizes

Progress bars are available in three sizes to cater for the diverse range of use cases and devices that our business uses.

<ThemedImage
  light={progressBarBehaviourSizes}
  dark={progressBarBehaviourSizesDark}
  alt=""
/>

### Progress

Different percentage indications are available in the variants to be chosen.
Percentages are 1%, 17%, 34% and 67% for the static component.

<ThemedImage
  light={progressBarBehaviourProgress}
  dark={progressBarBehaviourProgressDark}
  alt=""
/>

### State

By default, the progress bar is in Loading state.

We recommend using the Completed state to emphasize the end of the progress.
We also recommend using the Error state to make it obvious when the loading is encountering some issues.

<ThemedImage
  light={progressBarBehaviourState}
  dark={progressBarBehaviourStateDark}
  alt=""
/>

### Color

By default, progress bars are emphasized (primary theme). Providing a visual prominence.

For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen.

<ThemedImage
  light={progressBarBehaviourColor}
  dark={progressBarBehaviourColorDark}
  alt=""
/>

### Animation

The progress bar is animated by default thanks to the Interactive Components feature on Figma. If you would like to remove this capacity, uncheck the “animate” property.

All animations can be manually overwritten if you need other timings.

<ThemedImage
  light={progressBarBehaviourAnimation}
  dark={progressBarBehaviourAnimationDark}
  alt=""
/>

### Animation type

The indeterminate variant comes either as a bar bouncing from left to right or as an infinite loop. You can select each one in the property menu of the component.

<ThemedImage
  light={progressBarBehaviourAnimationType}
  dark={progressBarBehaviourAnimationTypeDark}
  alt=""
/>

## Usage Guidelines

### Use percentage based progress bar for longer loading delays.

- **Don’t**: use percentage based progress bar for delays between 2 and 9 seconds
- **Do**: use percentage based progress bar for delays > 10 seconds

<ThemedImage
  light={
    progressBarUsageGuidelinesUsePercentageBasedProgressBarForLongerLoadingDelays
  }
  dark={
    progressBarUsageGuidelinesUsePercentageBasedProgressBarForLongerLoadingDelaysDark
  }
  alt=""
/>

### Use loop based progress bar for shorter loading times.

- **Don’t**: use loop based progress bar for delays over 10 seconds
- **Do**: use loop based progress bar for delays < 10 seconds

<ThemedImage
  light={
    progressBarUsageGuidelinesUseLoopBasedProgressBarForShorterLoadingTimes
  }
  dark={
    progressBarUsageGuidelinesUseLoopBasedProgressBarForShorterLoadingTimesDark
  }
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=12100-289548&t=kOWgyuqnVCEtliGV-4)



# Progress Circle

<ThemedImage light={progressCircle} dark={progressCircleDark} alt="" />

## Overview

A progress circle is a progress indicator, either determinate (indicating a percentage of progression) or indeterminate (indicating a state of loading).

### Usage

When to use:

- When managing action like download, upload, retrieval of data, …
- When the system is temporarily disabled, to block the screen
- When the processing takes more than a few seconds
- Generally, to provide feedback to the user about progression.

## Anatomy

<ThemedImage
  light={progressCircleAnatomy}
  dark={progressCircleAnatomyDark}
  alt=""
/>

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Progress Circle

| Property     | Values                                             | Default     |
| ------------ | -------------------------------------------------- | ----------- |
| **variant**  | determinate / indeterminate                        | determinate |
| **size**     | xsmall / small / medium / large / xlarge / xxlarge | xsmall      |
| **color**    | primary / neutral                                  | primary     |
| **progress** | 0% / 50% / 100% / N/A                              | 0%          |
| **step**     | step-1 / step-2 / step-3 / step-4 / N/A            | N/A         |
| **track**    | true / false                                       | true        |

## Behaviour

### Determinate & Indeterminate

The progress circle comes in two different types, segregated into two main components.

The determinate type, when progress can be calculated against a target (download, upload, know sizes, …)

The indeterminate type, when there is progress but the completion cannot be determined (connection to a server, retrieving unknown amount of data, …)

<ThemedImage
  light={progressCircleBehaviourDeterminateIndeterminate}
  dark={progressCircleBehaviourDeterminateIndeterminateDark}
  alt=""
/>

### Sizes

Progress circles are available in five sizes to cater for the diverse range of use cases and devices that our business uses.

<ThemedImage
  light={progressCircleBehaviourSizes}
  dark={progressCircleBehaviourSizesDark}
  alt=""
/>

### Background

The Progress circle has a background (track) by default. You can choose to remove the background to adapt for different use cases and interfaces styles.

<ThemedImage
  light={progressCircleBehaviourBackground}
  dark={progressCircleBehaviourBackgroundDark}
  alt=""
/>

### Colour emphasis

By default, progress circles are emphasized (primary theme). Providing a visual prominence.

For visual components where you don’t want to emphasize the progress circle component, the neutral theme is more appropriate for this de-prioritize its focus on the screen.

<ThemedImage
  light={progressCircleBehaviourColourEmphasis}
  dark={progressCircleBehaviourColourEmphasisDark}
  alt=""
/>

### Progress indication

The determinate variant comes in 3 main progress steps: 0%, 50% and 100%.
Those steps are mainly used for animation purpose, but you can choose to use them as static.

The indeterminate variant comes in 4 main progress steps: Step 1, Step 2, Step 3 & Step 4.
Those steps are mainly used for animation purpose, but you can choose to use them as static.

<ThemedImage
  light={progressCircleBehaviourProgressIndication}
  dark={progressCircleBehaviourProgressIndicationDark}
  alt=""
/>

### Progress Animation

The progress circle is animated by default thanks to the Interactive Components feature on Figma. If you would like to remove this capacity, you need to deactivate it in the prototyping panel.

The indeterminate variant comes as an infinite loader with a 360° rotation every second.
The determinate variant moves from 0% to 50% in 3s, and from 50% to 100% in 2.5s for a total cycle of 5.5s.

This can be manually overwritten if you need other timings.

<ThemedImage
  light={progressCircleBehaviourProgressAnimation}
  dark={progressCircleBehaviourProgressAnimationDark}
  alt=""
/>

## Usage Guidelines

### Use the different sizes to match the use cases

- **Don’t**: try to fit large sizes in non-adapted layouts.
- **Do**: adapt the size for each use case (matching contextual icon sizes, for example)

<ThemedImage
  light={progressCircleUsageGuidelinesUseTheDifferentSizesToMatchTheUseCases}
  dark={progressCircleUsageGuidelinesUseTheDifferentSizesToMatchTheUseCasesDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284041&t=kOWgyuqnVCEtliGV-4)



# Card

<ThemedImage light={card} dark={cardDark} alt="" />

## Overview

Cards are surfaces that display content and actions on a single topic.
They should be easy to scan for relevant and actionable information. Elements, like text and images, should be placed on them in a way that clearly indicates hierarchy.

<Alert type="warn">
  The Card component needs strong Figma skills from designers, with the use of
  auto layout and layer constraints. These skills are needed to customize the
  create by creating your own assets to suit your needs, but default assets are
  already created to help you.
</Alert>

### Usage

When to use:

- To wrap linked informations into a container.
- To display content and actions on a single topic inside a container.
- To visually separate specific parts of content in a view using a padded background color.
- To show data visualisation.
- Use in groups to link similar items and to show homogeneous or heterogeneous content.

When not to use:

- When you need to capture user’s attention in a prominent way.
- To inform the user about important changes or conditions in the interface.
- When you need to have multiple primary action buttons.

### Sources

- [Cards: UI-Component Definition](https://www.nngroup.com/articles/cards-component/) by Nielsen Norman Group
- [Card UI Examples and Best Practices](https://www.eleken.co/blog-posts/card-ui-examples-and-best-practices-for-product-owners) by eleken
- [Card UI design: fundamentals and examples](https://www.justinmind.com/ui-design/cards) by Justinmind

## Anatomy

The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it.

<ThemedImage light={cardAnatomy} dark={cardAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### Component: Card (Horizontal & Vertical)

| Property   | Values        | Default      |
| ---------- | ------------- | ------------ |
| **border** | false / true  | false        |
| **shadow** | false / true  | true         |
| **Slot 1** | false / true  | true         |
| **Slot 1** | instance swap | Layout block |
| **Slot 2** | false / true  | true         |
| **Slot 2** | instance swap | Layout block |
| **Slot 3** | false / true  | true         |
| **Slot 3** | instance swap | Layout block |
| **Slot 4** | false / true  | true         |
| **Slot 4** | instance swap | Layout block |

#### Sub-component: Custom Slot

| Property      | Values                | Default  |
| ------------- | --------------------- | -------- |
| **direction** | horizontal / vertical | vertical |

## Assets

The assets are the small bricks made available to the designers to easily complete their cards. They are intended to be placed in the blue swap areas. These assets are the foundations on which designers will have to create and add their own assets in order to fit their needs perfectly.

### How to create your own asset

Here is a short tutorial to allow the designer to create custom content.

#### Tutorial #1

<ThemedImage
  light={cardAssetsHowToCreateYourOwnAssetTutorial1}
  dark={cardAssetsHowToCreateYourOwnAssetTutorial1Dark}
  alt=""
/>

#### Tutorial #2 - Recreate a horizontal card

<ThemedImage
  light={cardAssetsHowToCreateYourOwnAssetTutorial2}
  dark={cardAssetsHowToCreateYourOwnAssetTutorial2Dark}
  alt=""
/>

#### Tutorial #3 - Recreate a vertical card

<ThemedImage
  light={cardAssetsHowToCreateYourOwnAssetTutorial3}
  dark={cardAssetsHowToCreateYourOwnAssetTutorial3Dark}
  alt=""
/>

### Assets library

Your favourite design system team has prepared a few assets for you in advance, which are available in the "Card/Assets/" folder when swapping a custom slot from the properties panel. It's your starter pack to get you rolling!

#### Header

<ThemedImage
  light={cardAssetsAssetsLibraryHeader}
  dark={cardAssetsAssetsLibraryHeaderDark}
  alt=""
/>

#### Title with text

<ThemedImage
  light={cardAssetsAssetsLibraryTitleWithText}
  dark={cardAssetsAssetsLibraryTitleWithTextDark}
  alt=""
/>

#### Button kit

<ThemedImage
  light={cardAssetsAssetsLibraryButtonKit}
  dark={cardAssetsAssetsLibraryButtonKitDark}
  alt=""
/>

#### Image and button

<ThemedImage
  light={cardAssetsAssetsLibraryImageAndButton}
  dark={cardAssetsAssetsLibraryImageAndButtonDark}
  alt=""
/>

#### Icon

<ThemedImage
  light={cardAssetsAssetsLibraryIcon}
  dark={cardAssetsAssetsLibraryIconDark}
  alt=""
/>

#### Weather

<ThemedImage
  light={cardAssetsAssetsLibraryWeather}
  dark={cardAssetsAssetsLibraryWeatherDark}
  alt=""
/>

## Templates

Find here some card templates to help make the complexity of the card component more understandable, via the presentation of tangible applications from a end-user perspective.

### 1. Card as contextual indicator

<ThemedImage
  light={cardTemplatesCardAsAContextualIndicator}
  dark={cardTemplatesCardAsAContextualIndicatorDark}
  alt=""
/>

### 2. Card as an horizontal tile with visual

<ThemedImage
  light={cardTemplatesCardAsAnHorizontalTileWithVisual}
  dark={cardTemplatesCardAsAnHorizontalTileWithVisualDark}
  alt=""
/>

### 3. Card as a vertical tile with visual

<ThemedImage
  light={cardTemplatesCardAsAVerticalTileWithVisual}
  dark={cardTemplatesCardAsAVerticalTileWithVisualDark}
  alt=""
/>

### 4. Card as a data visualisation

<ThemedImage
  light={cardTemplatesCardAsADataVisualisation}
  dark={cardTemplatesCardAsADataVisualisationDark}
  alt=""
/>

## Usage Guidelines

### Be concise in the card content

- **Don’t**: Overwhelm the space with excessive content
- **Do**: Include essential, summarized information

<ThemedImage
  light={cardUsageGuidelinesBeConciseInTheCardContent}
  dark={cardUsageGuidelinesBeConciseInTheCardContentDark}
  alt=""
/>

### Be consistent in the content of grouped cards

- **Don’t**: Group different cards that use different elements
- **Do**: Use consistent elements from card to card to represent clear listing pattern

<ThemedImage
  light={cardUsageGuidelinesBeConsistentInTheContentOfGroupedCards}
  dark={cardUsageGuidelinesBeConsistentInTheContentOfGroupedCardsDark}
  alt=""
/>

### Make cards easy to read

- **Don’t**: Unaligned elements make the card hardly scannable
- **Do**: Card correctly aligned make the action buttons easier to use

<ThemedImage
  light={cardUsageGuidelinesMakeCardsEasyToRead}
  dark={cardUsageGuidelinesMakeCardsEasyToReadDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=17815-446838&t=kOWgyuqnVCEtliGV-4)



# Divider

<ThemedImage light={divider} dark={dividerDark} alt="" />

## Overview

Dividers help you bring rhythm and clarity to your interfaces by separating elements. Separation of elements also comes in pair with the grouping of ones, thus a powerful tool to raise your information architecture.

## Anatomy

<ThemedImage light={dividerAnatomy} dark={dividerAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Component: Divider

| Property        | Values                 | Default    |
| --------------- | ---------------------- | ---------- |
| **size**        | small / medium / large | medium     |
| **orientation** | horizontal / vertical  | horizontal |
| **shape**       | rounded / sharp        | rounded    |

## Behaviour

### Sizes

The divider comes in three sizes to cater for the diverse range of use:

- Small
- Medium
- Large

By default, the divider comes in Medium size but should always be adapted to match the layout density of your interfaces.

<ThemedImage
  light={dividerBehaviourSizes}
  dark={dividerBehaviourSizesDark}
  alt=""
/>

### Orientation

The divider can be used in two main directions:

- Horizontal - to separate items on the vertical axis
- Vertical - to separate items on the horizontal axis

<ThemedImage
  light={dividerBehaviourOrientation}
  dark={dividerBehaviourOrientationDark}
  alt=""
/>

### Shape

The divider can be used in two main shapes:

- Rounded - should be used when the divider is not 100% of the height/width of its container
- Sharp - should be used when the divider is 100% of the height/width of its container

<ThemedImage
  light={dividerBehaviourShape}
  dark={dividerBehaviourShapeDark}
  alt=""
/>

## Usage Guidelines

### Don’t use rounded dividers edge on edge

- **Don’t**: let rounded edge touch container edges.
- **Do**: use sharp variant instead.

<ThemedImage
  light={dividerUsageGuidelinesDonTUseRoundedDividersEdgeOnEdge}
  dark={dividerUsageGuidelinesDonTUseRoundedDividersEdgeOnEdgeDark}
  alt=""
/>

### Overuse of dividers

- **Don’t**: add too much noise by overusing dividers.
- **Do**: use them sparingly to highlight your information architecture.

<ThemedImage
  light={dividerUsageGuidelinesOveruseOfDividers}
  dark={dividerUsageGuidelinesOveruseOfDividersDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284049&t=kOWgyuqnVCEtliGV-4)



# Tag

<ThemedImage light={tag} dark={tagDark} alt="" />

## Overview

Tags allow users to categorize, label or organise content using keywords.

### Usage

When to use:

- Filter data, using the tags to show only items within that particular category.
- Map content to multiple categories or statuses, helping the user to differentiate between them.
- Trigger actions, such as page filters or routing.

When not to use:

- It is purely for decorative purposes.

## Anatomy

<ThemedImage light={tagAnatomy} dark={tagAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ❖ Components: Tags (All colours)

| Property        | Values                              | Default |
| --------------- | ----------------------------------- | ------- |
| **size**        | small / medium                      | medium  |
| **shape**       | rounded / sharp                     | rounded |
| **\*state**     | default / hover / pressed / focused | default |
| **selected**    | false / true                        | false   |
| **disabled**    | false / true                        | false   |
| **label**       | text                                | Label   |
| **\*hasIcon**   | boolean                             | true    |
| **icon**        | instance swap                       | train   |
| **dismissible** | boolean                             | true    |

## Behaviour

### Using tags for input

#### Simplifying information

Tags can be used in text inputs to represent a complex piece of information in a compact form, such as an entity (person, place or thing).

<ThemedImage
  light={tagBehaviourUsingTagsForInputSimplifyingInformation}
  dark={tagBehaviourUsingTagsForInputSimplifyingInformationDark}
  alt=""
/>

#### Placement

Tags can be placed into input components in multiple ways. They can appear:

- Inline with the text input cursor in a field
- In a stacked list
- In a horizontally scrollable list

<ThemedImage
  light={tagBehaviourUsingTagsForInputPlacement}
  dark={tagBehaviourUsingTagsForInputPlacementDark}
  alt=""
/>

### Using tags for selection

#### Selecting a mutually exclusive option

Tags can be used to select a single tag from a set of options.

They clearly delineate and display options in a compact area. They are a good alternative to [radio buttons](/docs/components/radio-button), and [dropdown menus](/docs/components/dropdown-menu).

<ThemedImage
  light={tagBehaviourUsingTagsForSelectionSelectingAMutuallyExclusiveOption}
  dark={tagBehaviourUsingTagsForSelectionSelectingAMutuallyExclusiveOptionDark}
  alt=""
/>

### Using tags to filter

#### Filtering content

Tags can be used to filter content.

They clearly delineate and display options in a compact area. They are a good alternative to [checkboxes](/docs/components/checkbox).

<ThemedImage
  light={tagBehaviourUsingTagsToFilterFilteringContent}
  dark={tagBehaviourUsingTagsToFilterFilteringContentDark}
  alt=""
/>

### Using tags as actions

#### Triggering actions

Tags offer actions related to primary content. They should appear dynamically and contextually in a UI and are an alternative to [buttons](/docs/components/button).

<ThemedImage
  light={tagBehaviourUsingTagsAsActionsTriggeringActions}
  dark={tagBehaviourUsingTagsAsActionsTriggeringActionsDark}
  alt=""
/>

## Usage Guidelines

### Use tags as a group

- **Don’t**: use tags if the intention is to use it as a single element, use a button or a link as a better alternative.
- **Do**: use tags in groups, that’s what they are made for.

<ThemedImage
  light={tagUsageGuidelinesUseTagsAsAGroup}
  dark={tagUsageGuidelinesUseTagsAsAGroupDark}
  alt=""
/>

## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=3897-97874&t=kOWgyuqnVCEtliGV-4)



# Data Table

<ThemedImage light={dataTable} dark={dataTableDark} alt="" />

## Overview

<div class="docs-data-table-alerts">
  <Alert type="info">
    This version of Data Table is a minimal version of the original component. You can access the [Figma | Data Table full version](https://www.figma.com/design/EmGJQrpKahu20roFakczvj/-Light--Data-Table-full-version--Copy-?node-id=24-157245&t=b0GunnHXUPzWUXrM-0).
  </Alert>

  <Alert type="warn">
    The Data Table component needs strong Figma skills from designers, with the use of auto layout and layer constraints.
    These skills are needed to customize the component by creating your own assets according to your needs. However, default assets are already created to help you.
    In addition, due to the complexity of the component, some visual bugs may occur.
  </Alert>
</div>

### Usage

When to use:

- If you have a lot of information to display
- If you want to organize your data in a grid-like format
- If you want to list a bunch of items

When not to use:

- If you have little enough information to display
- If you are constrained with space

### Sources

- [Data table](https://carbondesignsystem.com/components/data-table/usage/) by Carbon Design System
- [Data table](https://m2.material.io/components/data-tables) by Material Design

## Anatomy

The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it.

<ThemedImage light={dataTableAnatomy} dark={dataTableAnatomyDark} alt="" />

### Properties

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant.

<Alert type="info" title="Heads up">
  A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries).

[Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0)

</Alert>

#### ◇◇◇◇❖ Cell

| Property           | Values                 | Default |
| ------------------ | ---------------------- | ------- |
| **Size**           | Small / Medium / Large | Medium  |
| **Margin density** | Small / Medium / Large | Medium  |
| **Sub-item**       | True / False           | False   |
| **IsVisible?**     | True / False           | False   |

#### ◇◇◇❖ Item

| Property           | Values                                                                   | Default |
| ------------------ | ------------------------------------------------------------------------ | ------- |
| **Size**           | Small / Medium / Large                                                   | Medium  |
| **Margin density** | Small / Medium / Large                                                   | Medium  |
| **Type**           | Text / Action button / Tag / Icon button / Checkbox / Icon / Custom slot | Text    |

#### ◇◇❖ Item list

| Property           | Values                                                                   | Default |
| ------------------ | ------------------------------------------------------------------------ | ------- |
| **Size**           | Small / Medium / Large                                                   | Medium  |
| **Margin density** | Small / Medium / Large                                                   | Medium  |
| **Type**           | Text / Action button / Tag / Icon button / Checkbox / Icon / Custom slot | Text    |
| **Header cell**    | True / False                                                             | True    |
| **Lines**          | True / False                                                             | True    |

#### ◇❖ Array

| Property           | Values                       | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Small / Medium / Large       | Medium  |
| **Margin density** | Small / Medium / Large       | Medium  |
| **Style**          | Lines / Grid / Zebras / Flat | Lines   |

#### ❖ Data table

| Property         | Values                 | Default |
| ---------------- | ---------------------- | ------- |
| **Size**         | Small / Medium / Large | Medium  |
| **◇ Toolbar**    | Nested component       | --      |
| **◇ Array**      | Nested component       | --      |
| **◇ Pagination** | Nested component       | --      |

## Behaviour

Component behaviour helps to present the states and use cases that the component might encounter.

### Toolbar

You can customize your toolbar by modifying its content: either actions, or custom content, and support information architecture with title according to your needs.
In case you don't want to display this component, an option is available in the Data Table properties.

<ThemedImage
  light={dataTableBehaviourToolbar}
  dark={dataTableBehaviourToolbarDark}
  alt=""
/>

### Pagination

Note: a section dedicated to pagination is available here.
The proposed pagination allows you to navigate through multi-page tables quickly. You will be able to navigate between pages, or even reach dedicated pages through the dropdown to instead consult the number of items in the table.
In case you don't want to display this component, an option is available in the Data Table properties.

<ThemedImage
  light={dataTableBehaviourPagination}
  dark={dataTableBehaviourPaginationDark}
  alt=""
/>

### Size

The table is available in 3 sizes: small, medium and large. This refers to the width & height of the items inside, margins and heights of the rows inside the table.
The component was designed in an average size of 1076px, which corresponds to desktop-sized usage with a drawer. You can adapt the width to your visuals in order to maintain a comfortable density of information, but we recommend you avoiding table usages with too many columns when the width is too small (like a smartphone).

<ThemedImage
  light={dataTableBehaviourSize0}
  dark={dataTableBehaviourSize0Dark}
  alt=""
/>
<ThemedImage
  light={dataTableBehaviourSize1}
  dark={dataTableBehaviourSize1Dark}
  alt=""
/>

### Margin density

The margin density makes it possible to ventilate more or less a table, according to the available space and the purpose of the table. Indeed, a table presenting a large amount of data will be more relevant with a low density.

<ThemedImage
  light={dataTableBehaviourMarginDensity}
  dark={dataTableBehaviourMarginDensityDark}
  alt=""
/>

### Styles

Tables are available in four styles: lines, grid, zebras and flat to help you enhancing the data and ease the reading.

<ThemedImage
  light={dataTableBehaviourStyles0}
  dark={dataTableBehaviourStyles0Dark}
  alt=""
/>
<ThemedImage
  light={dataTableBehaviourStyles1}
  dark={dataTableBehaviourStyles1Dark}
  alt=""
/>

### Columns types

The Data Table is delivered with several cell types such as text area, action button, checkbox, icon etc. To be as flexible as possible these cells are sorted in two categories:

- **default size** columns for common data and actions: it will fill all the space available
- **small** columns for icons, icon buttons or checkboxes which has a fixed width to optimize space in your data table

We recommend you to customize the behavior of each column if you have specific needs.

<ThemedImage
  light={dataTableBehaviourColumnTypes}
  dark={dataTableBehaviourColumnTypesDark}
  alt=""
/>

### Sub-items

Each line can have sub-items. This can be helpful to display data related to the main item without having too much items shown at the same time.

<ThemedImage
  light={dataTableBehaviourSubItems}
  dark={dataTableBehaviourSubItemsDark}
  alt=""
/>

### Header cell style

The Header cell is available in different styles to support Data table emphasis.
By default, Data tables are emphasized (primary color). Providing a visual prominence.

In case you don’t want to emphasize the Data table component, Light and Neutral styles are more appropriate for visual de-prioritization on the screen.

In Light variant, the background of the Header cell is transparent and adapts to the background of your surface.

<ThemedImage
  light={dataTableBehaviourHeaderCellStyle}
  dark={dataTableBehaviourHeaderCellStyleDark}
  alt=""
/>

### Cell types

All columns can be switched with many options:

- **Text cell**: the default cell with left-aligned text. You can adjust it to the data that it will contain. It is also possible to display an icon at the left or right.
- **Action button & Icon button**: we recommend to use it at the end of the line to gather all the actions related to the lines.
- **Tag**: it allows to highlight information such as status, contact, documents etc.
- **Custom slot**: so you can add your own components.
- **Checkbox**: the checkbox is by default hidden in the sub-items but you can display it if necessary. It is also visible in the Header cell for a "select all" behaviour.
- **Icon**: as for the checkbox, the icon is by default hidden in the sub-items because we recommend its use in the first column as to signify an expand/collapse of the sub-items.

<ThemedImage
  light={dataTableBehaviourCellTypes}
  dark={dataTableBehaviourCellTypesDark}
  alt=""
/>

### Cell visibility

Each cell has a property to show or hide its contents. This can be useful for information that is not presented in all the cells of the same column.

<ThemedImage
  light={dataTableBehaviourCellVisibility}
  dark={dataTableBehaviourCellVisibilityDark}
  alt=""
/>

## Usage Guidelines

Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts.

### Adapt the width to the data

- **Don’t**: truncate text if you have more space in other columns
- **Do**: adapt the width of big columns to their contents

<ThemedImage
  light={dataTableUsageGuidelinesAdaptTheWidthToTheData}
  dark={dataTableUsageGuidelinesAdaptTheWidthToTheDataDark}
  alt=""
/>

### Small screen use case

- **Don’t**: make the columns unreadable for small devices
- **Do**: use an horizontal scroll with a fixed column if necessary

<ThemedImage
  light={dataTableUsageGuidelinesSmallScreenUseCase}
  dark={dataTableUsageGuidelinesSmallScreenUseCaseDark}
  alt=""
/>

### Be consistent with your data

- **Don’t**: put several cell types in a same column
- **Do**: be consistent in your column types

<ThemedImage
  light={dataTableUsageGuidelinesBeConsistentWithYourData}
  dark={dataTableUsageGuidelinesBeConsistentWithYourDataDark}
  alt=""
/>

### Deal with multiple lines

- **Don’t**: center vertically the data and display various quantities of text according to the column
- **Do**: set a maximum of 2 lines of text and align lines to the top

<ThemedImage
  light={dataTableUsageGuidelinesDealWithMultipleLines}
  dark={dataTableUsageGuidelinesDealWithMultipleLinesDark}
  alt=""
/>

## Tips & tricks

Data table is a complex component, which is why it is important to know how to handle it.

### Structure

The Data Table has a column-based architecture, which allows you to change its structure quickly without having to go through all the different layers. So when we manipulate the table, we can quickly choose the number of columns to display.

Note: If you delete an item in a component instance, it will be hidden but not deleted. This can be handy if you want to hide an entire line for example.

<ThemedImage
  light={dataTableTipsTricksStructure}
  dark={dataTableTipsTricksStructureDark}
  alt=""
/>

### Resize quickly

If you are in the situation where you need to enlarge certain columns, the fastest and easiest way is to change the behavior of your columns. Select the column to enlarge and check that it is in "fill container", you can pass the others in "fixed width". If that's not enough, you can play with the "hug content" mode but it will depend on the content you want to display.

<ThemedImage
  light={dataTableTipsTricksResizeQuickly}
  dark={dataTableTipsTricksResizeQuicklyDark}
  alt=""
/>

### Hide/Show cell’s content

It is possible to make the content of a cell invisible by disabling its "IsVisible?" at the component level. This can be useful when using sub-items that do not contain all the elements of their parent, for example.

<ThemedImage
  light={dataTableTipsTricksHideShowCellSContent}
  dark={dataTableTipsTricksHideShowCellSContentDark}
  alt=""
/>



## Component Architecture

[Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=21500-446142&t=kOWgyuqnVCEtliGV-4)