Suggestion Chips
Wrapping row of clickable pills that emit a selection event when chosen.
Preview
<x-ui.suggestion-chips class="mx-auto w-full max-w-xl" />
Installation
php artisan ui:add suggestion-chips
Note
This component ships an Alpine behavior module at
resources/js/ui/suggestion-chips.js. Import it once from your bundle so it registers on alpine:init:
import './suggestion-chips.js';
Registry contract
php artisan ui:add suggestion-chips
writes only the files below. The CLI validates each file hash before writing and asks before it replaces a local change, unless you pass --force.
-
resources/views/components/ui/suggestion-chips.blade.php -
resources/js/ui/suggestion-chips.js
- Registry dependencies
- None — installs on its own.
- Packages
-
composer: jml/brok:^0.2npm: alpinejs
Use with AI
A brief for your coding agent: install command, usage, props, guidance and the rules. Copy it, or open a prompt about this component in an assistant.
# Brok UI: Suggestion Chips (`suggestion-chips`)
Wrapping row of clickable pills that emit a selection event when chosen.
Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.
## Install
```bash
php artisan ui:add suggestion-chips
```
## Usage
```blade
<x-ui.suggestion-chips class="mx-auto w-full max-w-xl" />
```
## Props
- `items` (array, default `['All', 'Popular', 'Recent', 'Favourites']`) — Labels rendered as chip buttons, in order.
## Use when
- Use when the option set is long enough that search, suggestion, or filtering speeds selection.
- Offering quick, client-side suggestions or filter shortcuts, such as search prompts or category shortcuts.
- Letting the host page react to a lightweight click event instead of a submitted form value.
## Avoid when
- Do not use advanced selection UI when a simpler visible control would be clearer.
- Submitting a value in a form; use label-selector or choicebox for a real form control.
- Needing multiple chips selected at once; suggestion-chips tracks a single selection.
## Anti-patterns
- Using advanced search for a tiny list
## Rules
- Use the `<brok:suggestion-chips>` tag (or `<x-ui.suggestion-chips>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.
## Links
- Docs: https://brokui.dev/docs/components/suggestion-chips
- Registry JSON (files, props, contract): https://brokui.dev/r/open/suggestion-chips.json
Working in Claude Code, Cursor or Codex? Give the agent the whole registry through the MCP server or the Brok UI skill.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| items | array | ['All', 'Popular', 'Recent', 'Favourites'] | Labels rendered as chip buttons, in order. |
Slots
default—
Data slots
Stable hooks for CSS overrides and browser tests.
Behavior
- Each chip is a real button; clicking one records it as the current selection and toggles its aria-pressed state.
- Selecting a chip dispatches a suggestion-chips-select CustomEvent with the chosen value in detail.value for the host page to act on.
- Chips wrap onto multiple lines in a flex row rather than scrolling horizontally.
- Installs a JavaScript behavior module when the registry item includes resources/js/ui files.
- Declares registry capability flags: a11y, interactive, responsive, rtl, darkMode, localized.
Guidance
Find and select within a long or uncertain option set.
Use when
- Use when the option set is long enough that search, suggestion, or filtering speeds selection.
- Offering quick, client-side suggestions or filter shortcuts, such as search prompts or category shortcuts.
- Letting the host page react to a lightweight click event instead of a submitted form value.
Avoid when
- Do not use advanced selection UI when a simpler visible control would be clearer.
- Submitting a value in a form; use label-selector or choicebox for a real form control.
- Needing multiple chips selected at once; suggestion-chips tracks a single selection.
Use instead
- Visible choices for small sets
- Dedicated filter panel for complex refinement
Anti-patterns
- Using advanced search for a tiny list
- Anatomy
- Theming hooks
Accessibility
- Keyboard
- native
- Focus
native
- Each chip is a native button with aria-pressed reflecting selection, so screen readers announce it as a toggle button.
- Chips are reachable and activatable with the keyboard alone, with no custom key handling required.
- Semantic HTML and a stable
data-slotattribute for styling and scripting hooks. - Focus-visible rings use the
ringtoken, so keyboard focus is always visible. - Disabled and invalid states are conveyed to assistive tech, not by color alone.
- Targets WCAG 2.2 AA; verify contrast in light, dark, admin and customer surfaces in the preview.
- Labels go through
__()and layout uses logical properties (ms-*,text-start), so it mirrors underdir="rtl"— flip the preview to RTL to confirm. - Dark mode uses the same semantic tokens under the
darkclass; high contrast follows forced-color system tokens.
Livewire
Add a stable wire:key when Livewire can reorder this interactive component.
<div wire:key="suggestion-chips-{{ $record->id }}">
<x-ui.suggestion-chips class="mx-auto w-full max-w-xl" />
</div>
Validation
Validation support: native. Keep the error message connected with aria-describedby.
<form wire:submit="save" class="space-y-2">
<brok:suggestion-chips
wire:model="value"
:aria-invalid="$errors->has('value') ? 'true' : 'false'"
aria-describedby="value-error"
/>
@error('value')
<p id="value-error" role="alert">{{ $message }}</p>
@enderror
<brok:button type="submit" wire:loading.attr="disabled">
<span wire:loading.remove>Save</span>
<span wire:loading>Saving…</span>
</brok:button>
</form>
Source
The exact, editable files ui:add writes
into your app. Previews render this same code; there are no preview-only components.
@props([
'items' => ['All', 'Popular', 'Recent', 'Favourites'],
])
{{--
Suggestion chips — a wrapping row of pills. Each is a real <button>, so it is
keyboard- and screen-reader-accessible. select() records the choice and
dispatches a `suggestion-chips-select` CustomEvent (detail.value) for the host to act on.
--}}
<div
x-data="uiSuggestionChips({ items: @js(array_values($items)) })"
data-slot="suggestion-chips"
{{ $attributes->merge(['class' => 'flex flex-wrap gap-2']) }}
>
<template x-for="(item, i) in items" :key="i">
<button
type="button"
@click="select(item)"
:aria-pressed="selected === item"
class="rounded-full border border-border bg-card px-3 py-2 text-sm text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
x-text="item"
></button>
</template>
</div>
/**
* Suggestion chips behavior.
*
* Renders a set of pills. Selecting one records it in `selected` and dispatches
* a bubbling `suggestion-chips-select` CustomEvent carrying the chosen text, so the
* host can act on the selection.
*/
document.addEventListener('alpine:init', () => {
window.Alpine.data('uiSuggestionChips', (cfg = {}) => ({
items: cfg.items ?? [],
selected: null,
select(item) {
this.selected = item;
this.$el.dispatchEvent(
new CustomEvent('suggestion-chips-select', {
detail: { value: item },
bubbles: true,
})
);
},
}));
});
Ownership & lifecycle
Owner, release state, review evidence and adoption for this item.
- Owner
- Platform UI (@JoshJML)
- Current version
-
2.0.4 - Status
- Stable
- License
-
open - Accessibility reviewed
- No review date recorded
- Last breaking change
- No date recorded
- Deprecation
- Not deprecated
- Contract
-
v6 - Foundation
-
≥ 1.0.0