Skip to content

Overview

The <x-aura::pillbox> component provides a multi-select input where selected values appear as removable pill badges. It includes a searchable dropdown for selecting from available options, a configurable maximum selection limit, and full Livewire integration via wire:model. The component supports label, hint, and error states for seamless form integration.

Pro component -- requires bluestarsystem/aura-ui-pro.

Use pillbox for:

  • Tag and category selectors
  • Multi-select filters
  • Skill or interest pickers
  • Any multi-value input with visual feedback

Basic Usage

<x-aura::pillbox
    label="Tags"
    :options="['Laravel', 'Livewire', 'Alpine.js', 'Tailwind']"
    wire:model="selectedTags"
/>

Props

Prop Type Default Description
label string|null null Label text displayed above the input
options array [] Available options. Accepts simple arrays or arrays of objects (see below)
optionLabel string 'label' Key for the display text when using object options
optionValue string 'value' Key for the value when using object options
searchable bool true Show a search input to filter options
max int|null null Maximum number of items that can be selected. null for unlimited
disabled bool false Disable the input
placeholder string 'Select...' Placeholder text for the search input
error string|null null Error message displayed below the input
hint string|null null Hint text displayed below the input (hidden when error is present)

Option Formats

Simple array (value and label are the same):

['Laravel', 'Vue', 'React', 'Svelte']

Associative array:

['laravel' => 'Laravel', 'vue' => 'Vue.js', 'react' => 'React']

Array of objects:

[
    ['label' => 'Laravel', 'value' => 'laravel'],
    ['label' => 'Vue.js', 'value' => 'vue'],
]

Variants / Examples

With Livewire

<x-aura::pillbox
    label="Skills"
    :options="$availableSkills"
    wire:model.live="selectedSkills"
    placeholder="Search skills..."
/>

With Maximum Limit

Select up to 3 categories.

<x-aura::pillbox
    label="Categories"
    :options="['Tech', 'Design', 'Marketing', 'Sales', 'HR']"
    :max="3"
    hint="Select up to 3 categories."
    wire:model="categories"
/>

With Validation Error

Please select at least one tag.

<x-aura::pillbox
    label="Tags"
    :options="$tags"
    wire:model="selectedTags"
    :error="$errors->first('selectedTags')"
    required
/>

Non-Searchable

<x-aura::pillbox
    label="Priority"
    :options="['Low', 'Medium', 'High', 'Critical']"
    :searchable="false"
    wire:model="priorities"
/>

Disabled State

<x-aura::pillbox
    label="Locked Tags"
    :options="['Read Only']"
    disabled
/>

Accessibility

  • The dropdown panel includes role="listbox" with aria-multiselectable="true" to indicate multi-select behavior.
  • Each option has role="option" with a dynamic aria-selected attribute reflecting its selection state.
  • Remove buttons on pills include aria-label="Remove" for screen reader identification.
  • The dropdown closes on outside click (@click.outside) and Escape key (@keydown.escape.window).
  • Options that exceed the max limit are visually dimmed with reduced opacity and cursor-not-allowed.