# Suggestion bar

A list of buttons shown below an input field that when clicked updates the input value

Tabs: [Guidelines](/components/web/suggestion-bar/suggestion-bar.guidelines.md) · [Code](/components/web/suggestion-bar/suggestion-bar.code.md)

## Basic usage

`SuggestionBar` renders each string in `suggestions` as a `selection` [Chip](/components/web/chip/chip.guidelines). Place it below the input it fills in. It is controlled: keep the selected index in state and update the input value in `onClick`.

```tsx
import {Input, Stack, SuggestionBar} from '@pleo-io/telescope'

const suggestions = ['Invoice date', '+ 7', '+ 14', '+ 30']

const DueDateInput = () => {
    const [value, setValue] = React.useState('')
    const [selectedSuggestion, setSelectedSuggestion] = React.useState<number>()

    return (
        <Stack space={8} stretch>
            <Input
                name="dueDate"
                value={value}
                onChange={(event) => {
                    setValue(event.target.value)
                    setSelectedSuggestion(undefined)
                }}
            />
            <SuggestionBar
                suggestions={suggestions}
                selectedSuggestion={selectedSuggestion}
                onClick={(index) => {
                    setSelectedSuggestion(index)
                    setValue(suggestions[index])
                }}
            />
        </Stack>
    )
}
```

`onClick` receives the index of the clicked suggestion. It is not called when the selected suggestion is clicked again, so clear `selectedSuggestion` (or derive it from the input value) when the user edits the input. Otherwise the suggestion stays pressed and can't be applied again.

## Icon or label

Use `icon` to render content before the suggestions, for example a label or an icon with a tooltip that explains where the suggestions come from.

```tsx
import {Text, Tooltip} from '@pleo-io/telescope'
;<SuggestionBar
    suggestions={['Acme Ltd']}
    onClick={handleClick}
    icon={
        <Tooltip content="Suggested from the invoice">
            <Text variant="body-s" color="colorContentStaticQuiet">
                Suggested
            </Text>
        </Tooltip>
    }
/>
```

## Single suggestion

For a single toggleable suggestion, for example "Use “Acme Ltd”", render a `selection` Chip directly instead of a `SuggestionBar` with one item. It can be deselected by clicking it again.

```tsx
<Chip variant="selection" active={isSelected} onClick={() => setIsSelected(!isSelected)}>
    Use “Acme Ltd”
</Chip>
```

## Testing

Each suggestion has a `data-testid` of `suggestion-{index}`. Pass `testId` to use your own test id for every suggestion.

## Accessibility

- Every suggestion is a `button` with `aria-pressed` set to whether it is selected, so it can be reached with Tab and activated with Enter or Space.
- Other props, such as `role="group"` and `aria-label`, are passed to the wrapper. Label the group when the input label alone does not explain what the suggestions are for.

## API reference

#### `icon`

Type: `ReactNode`

##### Allowed values

- `null`
- `string`
- `number`
- `bigint`
- `false`
- `true`
- `ReactElement<unknown, string | JSXElementConstructor<any>>`
- `Iterable<ReactNode>`
- `ReactPortal`
- `Promise<AwaitedReactNode>`

Default: -

Content rendered before the suggestions, for example a label or an icon with a tooltip.

#### `onClick` (required)

Type: `(index: number) => void`

Default: -

Called with the index of the clicked suggestion. Not called when the already selected suggestion is clicked again.

#### `selectedSuggestion`

Type: `number | undefined`

Default: -

Index of the selected suggestion, if any.

#### `suggestions` (required)

Type: `string[]`

Default: -

The suggestion labels, rendered as `selection` chips in the given order.

#### `testId`

Type: `string | undefined`

Default: `` `suggestion-${index}` ``

Test id applied to every suggestion.