Documentation

SelectChoice extends Component
in package

SelectChoice Laravel Blade Component

An enhanced select dropdown component powered by Choices.js for modern UI. Always includes Choices.js functionality with search, remove buttons, and enhanced UX. Supports both single/multiple selection, grouped options, and integrates seamlessly with Laravel's form validation and Livewire.

Features:

  • Single or multiple selection support
  • Grouped options (optgroups) support
  • Search functionality with customizable threshold
  • Remove buttons for multiple selections
  • Maximum item count limiting for multiple selection
  • Automatic label generation from name
  • Collection and array options support
  • Optional sorting of options
  • Form validation integration
  • Livewire real-time updates
  • Bulma CSS framework integration
  • Always enhanced with Choices.js library

Livewire Integration:

IMPORTANT: When using multiple selection (multiple=true), DO NOT use wire:model. The component handles Livewire communication through custom events.

Events Dispatched:

  • SelectChoiceUpdated:{{ $id }} - Fired when selection changes Payload: { value: string|array|null }

Events Listened For:

  • SelectChoiceReset:{{ $id }} - Clears all selected items
  • SelectChoiceRemoveValue:{{ $id }} - Removes specific value(s) Payload: { value: string|array }
Tags
author

Laravel Developer

version
1.0.0
since
2025-12-20
example

example

<x-select-choice name="skills" :options="$skills" :multiple="true" :maxItemCount="3" placeholder="Select up to 3 skills" />

example

example

Table of Contents

$choicesConfig  : string
Choices.js configuration as JSON string
$class  : string
Additional CSS classes (processed)
$hint  : string|null
$id  : string
The HTML id attribute (generated from name if not provided)
$label  : string|false|null
$maxItemCount  : int|null
$multiple  : bool
$name  : string
$options  : array<string|int, mixed>
Processed options array after normalization
$placeholder  : string|null
$value  : string|array<string|int, mixed>|null
__construct()  : mixed
Create a new SelectChoice component instance
getProcessedLabel()  : string|false|null
Get the processed label (auto-generated if null, false to hide)
isSelected()  : bool
Check if a value is selected
render()  : View|Closure|string
Get the view / contents that represent the component
generateChoicesConfig()  : string
Generate Choices.js configuration
generateId()  : string
Generate HTML ID from component name
processClasses()  : string
Process CSS classes from various input formats
processOptions()  : array<string|int, mixed>
Process and normalize options from various input formats

Properties

$choicesConfig

Choices.js configuration as JSON string

public string $choicesConfig = ''

$class

Additional CSS classes (processed)

public string $class = ''

$id

The HTML id attribute (generated from name if not provided)

public string $id

$options

Processed options array after normalization

public array<string|int, mixed> $options = []

$value

public string|array<string|int, mixed>|null $value = null

Methods

__construct()

Create a new SelectChoice component instance

public __construct(string $name[, array<string|int, mixed>|Collection $options = [] ][, string|array<string|int, mixed>|null $value = null ][, bool $multiple = true ][, string|null $placeholder = null ][, string|null $id = null ][, string|false|null $label = null ][, string|array<string|int, mixed>|null $classes = null ][, string|null $hint = null ][, int|null $maxItemCount = null ][, bool $sort = false ]) : mixed
Parameters
$name : string

Required. The form input name

$options : array<string|int, mixed>|Collection = []

Available options (key-value pairs or nested arrays for groups)

$value : string|array<string|int, mixed>|null = null

Selected value(s) for single/multiple selection

$multiple : bool = true

Enable multiple selection (default: false for single selection) IMPORTANT: When true, DO NOT use wire:model attribute

$placeholder : string|null = null

Placeholder text for empty selection

$id : string|null = null

HTML id attribute (auto-generated from name if null)

$label : string|false|null = null

Display label (auto-generated from name if null, false to hide)

$classes : string|array<string|int, mixed>|null = null

Additional CSS classes (string or array)

$hint : string|null = null

Help text displayed below the select

$maxItemCount : int|null = null

Maximum number of items that can be selected (only for multiple selection)

$sort : bool = false

Whether to sort options alphabetically (default: false)

Tags
throws
InvalidArgumentException

When name is empty

Return values
mixed —

getProcessedLabel()

Get the processed label (auto-generated if null, false to hide)

public getProcessedLabel() : string|false|null
Return values
string|false|null —

The processed label string, false if hidden, null if not set

isSelected()

Check if a value is selected

public isSelected(mixed $optionValue) : bool
Parameters
$optionValue : mixed

The option value to check

Return values
bool —

Whether the value is selected

render()

Get the view / contents that represent the component

public render() : View|Closure|string
Return values
View|Closure|string —

The component view instance

generateChoicesConfig()

Generate Choices.js configuration

private generateChoicesConfig() : string

Builds the JSON configuration object for Choices.js initialization, including search settings, placeholder handling, and maxItemCount for multiple selection.

Return values
string —

JSON configuration for Choices.js

generateId()

Generate HTML ID from component name

private generateId(string $name) : string
Parameters
$name : string

Component name

Return values
string —

Generated HTML ID

processClasses()

Process CSS classes from various input formats

private processClasses(string|array<string|int, mixed>|null $classes) : string
Parameters
$classes : string|array<string|int, mixed>|null

CSS classes input

Return values
string —

Processed CSS classes string

processOptions()

Process and normalize options from various input formats

private processOptions(array<string|int, mixed>|Collection $options[, bool $sort = false ]) : array<string|int, mixed>
Parameters
$options : array<string|int, mixed>|Collection

Raw options input

$sort : bool = false

Whether to sort the options

Return values
array<string|int, mixed> —

Processed options array

Search results