# Chips

Chips are a flexible component that can be used for the selection of items from
a group while preserving vertical space in the interface.

## Design & usage guidelines

The Chip will allow users to make selections in scenarios where vertical space
is at a premium. It has three high-level usages: single-select, multi-select,
and add/dismiss selection.

### Web

### Single-select

If you need the user to make a selection of a single item from among several
items, and those items all have short (1–2 word) labels, single-select Chips
will allow the user to choose one of those items.

This preserves vertical space while allowing the user to clearly identify which
item they have selected.

Unlike [Radio](../RadioGroup/RadioGroup.md), the selected single-select Chip can be
de-selected by the user, leaving all selections blank.

### Multi-select

If you need the user to make a selection of one *or more* items from amongst
several items, and those items all have short (1–2 word) labels, a multi-select
Chips will allow the user to choose as many items from the group as they wish.

This preserves vertical space while allowing the user to clearly identify which
items they have selected. To signify to the user that multiple selections are
possible, a checkmark icon is present to reinforce the conceptual similarity to
a [Checkbox](../Checkbox/Checkbox.md).

Similar to Checkbox, a selected multi-select Chip can be de-selected by the
user, leaving all selections blank.

### Add/dismiss selection

> **WARNING:** "Selection" Chips have been deprecated and are no longer supported. Instead,
> please use [Autocomplete](../Autocomplete/Autocomplete.md) with the "multiple" prop.

When the user will be selecting one or more items by inputting their own Chip
options with, use the dismissible Chip.

The dismissible Chip allows them to remove previous selections from the Chips.
Use this option when the full list of possible selections is too great to
reasonably display in one group of Chip. For example, "all of my phone contacts"
would be far too many Chip options to present in one group, and would be
overwhelming for the user to interpret.

This format also allows the user to create their own "freeform" Chip options,
which they can also remove once added.

### Mobile

### Accent

Chip can be themed to one of Jobber's "workflow" colours in an active state when
the user may benefit from additional visual indication of the type of workflow
item selected.

### Dismissible

In cases where there are existing selections that the user may need to remove,
Chip can display a `cross` Icon signifying that these options can be removed.

### Inactive Background Color

In cases where the Chip is on an area whose background is
`--color-surface--background`, Chip can be made visible by specifying the
`inactiveBackgroundColor`.

## Related components

* [Chip](../Chip/Chip.md) is the building block that Chips is built on top of,
  and has more flexibility to be used in isolation.
* [RadioGroup](../RadioGroup/RadioGroup.md) should be used to allow the user to
  select "one-of-many" items (single-select) and the labels for the items are
  longer than 1 or 2 words.
* [Checkbox](../Checkbox/Checkbox.md) should be used to allow the user to select
  "one-or-more-of-many" items (multi-select) and the labels for the items are
  longer than 1 or 2 words.
* [InlineLabel](../InlineLabel/InlineLabel.md) should be used when you just need a
  rectangular element that displays the status of another element.

## Content guidelines

Chip labels should be 1–2 words at most. If any of the options in the group may
have longer labels, consider Checkbox or Radio as necessary for your selection
type.

## Accessibility

### Web

Chips should convey to the user whether it is a "checkbox" or "radio" element
based on single or multi-select. The Chips in this group have the appropriate
roles and keyboard operation to allow the user to interact as though they are
dealing with a checkbox or radio button.

If Chips is set for add/dismiss selections, the dismiss button will notify the
user that they will "dismiss {label name}" upon press.

### Mobile

Chip accessibilityRole by default is `radio` so the view containing it should
have the accessibilityRole `radiogroup`. Chip labels and the state `checked` or
`not checked` state are read aloud when focused by assistive technology. If an
Icon is present, it will not be read aloud as Icons are visually decorative in
the case of a Chip.

If the accessibilityRole is not `radio` the label is read aloud when focused by
assistive technology.

## Responsiveness

The Chips themselves will take up as much space as their container allows, and
the Chips will flow left to right. Chips may re-flow into new rows, or scroll
out of view in a single row, depending on your use case.


## Configuration

Standalone Chip's `role`, `<Chip.Prefix>`, `<Chip.Suffix>` `heading` and
`variation` will not work specifically when used within a `Chips`.

If you wish to use a prefix, please use `Chip` from `Chips/Chip`.

#### ✅ Do

```
import { Chip, Chips } from "@jobber/components/Chips";
...

<Chips>
  <Chip prefix="thumbsUp"/>
</Chips>
```

#### ❌ Don't

```
import { Chip, Chips } from "@jobber/components";

...
<Chips>
  <Chip>
    <Chip.Prefix>...</Chip.Prefix>
  </Chip>
</Chips>
```

## Developer notes

To override the appearance of the selected Chip(s) you may use
[Base Chip Color Overrides](/components/Chip/implement) since the selected Chip
is a Base Chip.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onChange` | `(value: string[]) => void` | Yes | — | Callback whenever a chip is clicked. This returns a new value of selected chips. |
| `selected` | `string[]` | Yes | — | Determines which chip gets highlighted. |
| `type` | `"dismissible"` | Yes | — | Change the interaction on the chip. |
| `activator` | `ReactElement<unknown, string | JSXElementConstructor<any>>` | No | — | Use a custom activator to trigger the Chip option selector |
| `autoSelectOnClickOutside` | `boolean` | No | `false` | If true, automatically selects an option based on the current search value when the input loses focus. The automatic ... |
| `isLoadingMore` | `boolean` | No | — | Adds a loading indicator |
| `onClick` | `(event: MouseEvent<HTMLInputElement | HTMLButtonElement | HTMLDivElement, MouseEvent>, clickedChipValue?: string) => void` | No | — | Callback when a specific chip is clicked @param event @param clickedChipValue - The value of the chip that was clicked |
| `onCustomAdd` | `(value: string) => void` | No | — | Callback when the user selects the custom option instead of the available chips.  If not implemented, it won't allow ... |
| `onLoadMore` | `(searchValue: string) => void` | No | — | Callback when the user scrolls at the end of the chip option list. Use this to load more options from the database. @... |
| `onlyShowMenuOnSearch` | `boolean` | No | `false` | Control whether the menu only appears once the user types. |
| `onSearch` | `(searchValue: string) => void` | No | — | Callback when a user types a word that filters the options. Use this when you need to query new options from the data... |