Skip to content

chips.mdx

Latest commit

 

History

History
629 lines (530 loc) · 24.4 KB

chips.mdx

File metadata and controls

629 lines (530 loc) · 24.4 KB
title Chips
description A chip is a UI element that captures filtering decisions across a series, a defined list of options, or recommended and predictive choices.
aliases
/docs/components/chips/
/docs/components/chip/
/docs/[[config:docs_version]]/components/chip/
toc true
types
Filter chip
Suggestion chip

import { getVersionedDocsPath } from '@libs/path'

You can find the OUDS design guidelines here: [filter chip guidelines](https://r.orange.fr/r/S-ouds-doc-filter-chip), [suggestion chip guidelines](https://r.orange.fr/r/S-ouds-doc-suggestion-chip).

Overview

Component types

  • Filter

    Filter chip is a UI element that enables users to select or deselect options within a series, commonly used to capture filtering decisions.

  • Suggestion

    Suggestion chip is a UI element that presents recommended or predictive options based on the user's input or context, often utilised to capture filtering decisions.

Approach

Chip components are always displayed in a containing <ul> list with a .chips-container class.

.chips-container manages the overall chip list layout.

.chip is the main class defining the chip component. It controls the placement inside the container and the click area.

.chip-interactive is the element that carries the interactive part of the component.

Accessibility

Semantics

For accessibility reasons, any informative element, must either be a semantic element itself or be wrapped in an appropriate semantic HTML element. Chips are always displayed as a list so they will always appear as <li>s inside a <ul> element.

Information for visually impaired users

Keep in mind that visually impaired and blind users will lack the visual context that permits to understand the chips list purpose on the page especially if chips' labels are not self-explanatory. Thus it's mandatory to add a semantically informative title to describe the chips' list purpose if possible, otherwise an aria-label on the containing ul must be added. To improve accessibility and denote the chips' list uniqueness of purpose, it's possible to add role=group on a parent container (but not the ul as it would lose its semantics).

Several examples are provided below but they will need to be adapted for actual use cases.

Pseudo elements

Here is a table summarizing the pseudo elements that are used by the different variants of the chip.

| chip variant | `.chip-interactive::before` | `.chip-interactive::after` | | ---| --- | --- | | Filter chip | Used | Used | | Suggestion chip | – | Used |

{/* | Filter expand chip | Used | Used | */}

[[comp]] Filter chip

Filter chip is a UI element that enables users to select or deselect options within a series, commonly used to capture filtering decisions.

Filter chip allows users to refine content by selecting or deselecting options. It can be toggled 'On' or 'Off' to adjust the displayed results, and selected filter chips remain visually distinct to show which filters are active.

They are based on checkbox inputs, but we also have button based or radio button based filter chips.

To create a filter chip, add .chip-filter to the .chip.

If possible, display a semantically informative title to describe the chips' list purpose like in the following example, otherwise an `aria-label` must be added to the `.chips-container` to explain the function of the chips. [Read more about chips accessibility here.](#accessibility)

<Example buttonLabel="basic filter chips" code={`

Filter by brands

  • Apple
  • Samsung
  • Xiaomi
`} />

Technical implementation

Using radio buttons

To have only one active filter chip at a time, use the radio button version. All the rules explained in this page about filter chips apply on this variant as well.

<Example buttonLabel="filter chips using radio buttons" code={`

  • Filter with radio 1
  • Filter with radio 2
  • Filter with radio 3

`} />

Using buttons

If you need to trigger a dynamic interaction directly on the page, <button> markup is also supported. All the rules explained in this page about filter chips apply on this variant as well.

Use our button JS plugin through data-bs-toggle="button" attribute, or handle interactivity on your side, but make sure to use aria-pressed to ensure a good level of accessibility:

  • The presence of aria-pressed (true or false) is mandatory to indicate to assistive technologies that this is a toggle button.
  • The selected styles of the filter chip rely on aria-pressed="true".

<Example buttonLabel="filter chips using buttons" code={`

  • Filter label using button 1
  • Filter label using button 2

`} />

Variants

Text and icon

To display an icon add the icon as the last child of the .chip-interactive.

<Example buttonLabel="text and icon filter chips" code={`

  • Filter with icon
  • Another filter with icon

`} />

Icon only

To display a chip with only an icon, add .chip-icon to the interactive part of the component.

Make sure to provide an accessible text for each chip.

<Example buttonLabel="icon only filter chips" code={`

  • Favorites
  • Technical

`} />

States

Disabled

Add disabled attribute either on the input or on the button element to disable the chip.

The following example shows every possible renderings depending on the filter chip type but it is not recommended to mix different types in a real use case.

<Example buttonLabel="disabled filter chips" code={`

  • Disabled checked filter
  • Disabled unchecked filter

`} />

Skeleton

<Example buttonLabel="filter chip skeleton" code={`

  • Filter chip
  • Filter chip

`} />

JavaScript

The button plugin allows you to create simple on/off toggle buttons.

Toggle states

Adding the attribute data-bs-toggle="button" enables the button JS plugin. Upon initialization, manually add aria-pressed="false" or aria-pressed="true" to indicate assistive technologies this is a toggle button, and its current state. When the state changes, the plugin will automatically update the aria-pressed value.

Methods

You can create a button instance with the button constructor, for example:

<Code buttonLabel="JavaScript to create a button instance" lang="js" code={const bsButton = new oudsWeb.Button('#myButton')} />

| Method | Description | | --- | --- | | `dispose` | Destroys an element’s button. (Removes stored data on the DOM element) | | `getInstance` | Static method which allows you to get the button instance associated with a DOM element, you can use it like this: `oudsWeb.Button.getInstance(element)`. | | `getOrCreateInstance` | Static method which returns a button instance associated with a DOM element or creates a new one in case it wasn’t initialized. You can use it like this: `oudsWeb.Button.getOrCreateInstance(element)`. | | `toggle` | Toggles push state. Gives the button the appearance that it has been activated. |

For example, to toggle all chips:

<Code buttonLabel="JavaScript to toggle all chips" lang="js" code={document.querySelectorAll('.chip-suggestion').forEach(chipElement => { const chip = oudsWeb.Button.getOrCreateInstance(chipElement) chip.toggle() })} />

[[comp]] Suggestion chip

Suggestion chip is a UI element that presents recommended or predictive options based on the user's input or context, often utilised to capture filtering decisions.

Suggestion chip is usually unselected by default and can be tapped or clicked to apply the suggestion, making input easier and improving usability.

To create a suggestion chip, add .chip-suggestion to the .chip.

If possible, display a semantically informative title to describe the chips' list purpose, otherwise an `aria-label` must be added to the `.chips-container` to explain the function of the chips, like in the following example. [Read more about chips accessibility here.](#accessibility)

<Example buttonLabel="basic suggestion chips" code={`

  • Thanks.
  • Looks good to me.
  • Can we talk about it later ?

`} />

Variants

Text and icon

To display an icon, add the icon as the first child of the .chip-interactive.

<Example buttonLabel="text and icon suggestion chips" code={`

  • Suggestion with icon 1
  • Suggestion with icon 2

`} />

Icon only

To display a chip with only an icon, add .chip-icon to the <button>.

Make sure to provide an accessible text for each chip.

<Example buttonLabel="icon only suggestion chips" code={`

  • I love it.
  • Go to parameters.

`} />

States

Disabled

Add disabled attribute on the button element to disable the chip.

The following example shows every possible renderings depending on the suggestion chip type but it is not recommended to mix different types in a real use case.

<Example buttonLabel="disabled suggestion chips" code={`

  • Thanks.
  • Suggestion with icon 1
  • Send "Go to parameters."

`} />

Skeleton

<Example buttonLabel="suggestion chip skeleton" code={`

  • Thanks.
  • Suggestion chip

`} />

Layout

This layout section applies to both chip component types.

Overflowing

By default when using .chips-container the chip list will scroll horizontally on one line.

<Example buttonLabel="overflowing suggestion chips" code={`

  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label

`} />

Wrapping

Add .flex-wrap on the .chips-container element to display a wrapping list of chips. Beware with this option as it could take too much vertical space on mobile viewports, as a rule there should not be more than 2 or 3 lines of chips displayed.

<Example buttonLabel="wrapping suggestion chips" code={`

  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label

`} />

Mix of both

For some use cases, mixing wrapping and overflowing can lead to a better UX.

This layout combines wrapping and vertical scrolling, please note that a style="max-height: 115px;" is added since we don’t want to display more than 2 or 3 lines, and still show part of the following line as a visual clue when the scrollbar is not displayed.

<Example buttonLabel="wrapping and overflowing suggestion chips" code={`

  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label
  • Quite long label

`} />