Skip to content
Brok UI

Loading…

No results

Suggestion Chips

Open source

Wrapping row of clickable pills that emit a selection event when chosen.

Version
v2.0.4
Stability
stable
License
MIT
Related
Label Selector
Choicebox
Tags Input

Preview

previews.components.suggestion-chips.default.blade.php Blade
<x-ui.suggestion-chips class="mx-auto w-full max-w-xl" />

Installation

terminal
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:

resources/js/ui/index.js JS
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.

  • blade resources/views/components/ui/suggestion-chips.blade.php
  • js resources/js/ui/suggestion-chips.js
Registry dependencies
None — installs on its own.
Packages
composer: jml/brok:^0.2
npm: 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.

suggestion-chips.md
# 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

manifest knowledge + registry-derived coverage

Props

Props accepted by this component: name, type, default value and description.
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.

suggestion-chips

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

Searchable selection and filtering

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
root
Theming hooks
suggestion-chips

Accessibility

WCAG 2.2 AA Keyboard focus-visible RTL-ready Localized labels Dark mode
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-slot attribute for styling and scripting hooks.
  • Focus-visible rings use the ring token, 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 under dir="rtl" — flip the preview to RTL to confirm.
  • Dark mode uses the same semantic tokens under the dark class; high contrast follows forced-color system tokens.

Livewire

Needs wire:key

Add a stable wire:key when Livewire can reorder this interactive component.

livewire-component.blade.php Blade
<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.

livewire-form.blade.php Blade
<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.

resources/views/components/ui/suggestion-chips.blade.php Blade
@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>
resources/js/ui/suggestion-chips.js JS
/**
 * 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