Documentation

SelectCheck extends Component
in package

SelectCheck Laravel Blade Component

An enhanced select dropdown component powered by VirtualSelect.js for modern UI. Always includes VirtualSelect.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 VirtualSelect.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:

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

Events Listened For:

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

Laravel Developer

version
1.0.0
since
2025-12-22
example

example

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

example

example

Table of Contents

$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
$virtualSelectConfig  : string
VirtualSelect.js configuration as JSON string
__construct()  : mixed
Create a new SelectCheck component instance
getProcessedLabel()  : string|false|null
Get the processed label for the component
isSelected()  : bool
Check if a specific option value is currently selected
render()  : View|Closure|string
Get the view / contents that represent the component
generateId()  : string
Generate HTML ID from component name
generateVirtualSelectConfig()  : string
Generate VirtualSelect.js configuration
processClasses()  : string
Process CSS classes from various input formats
processOptions()  : array<string|int, mixed>
Process and normalize options from various input formats

Properties

$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 = []

$placeholder

public string|null $placeholder = null

$value

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

$virtualSelectConfig

VirtualSelect.js configuration as JSON string

public string $virtualSelectConfig = ''

Methods

__construct()

Create a new SelectCheck 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: true for multiple 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

throws
InvalidArgumentException

When maxItemCount is not a positive integer

throws
InvalidArgumentException

When maxItemCount exceeds available options count

Return values
mixed —

getProcessedLabel()

Get the processed label for the component

public getProcessedLabel() : string|false|null

Handles three states:

  • false: Explicitly hide the label
  • string: Use the provided label text
  • null: Auto-generate a human-readable label from the component name
Return values
string|false|null —

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

isSelected()

Check if a specific option value is currently selected

public isSelected(mixed $optionValue) : bool

Handles both single and multiple selection modes:

  • Single selection: Compares the value directly
  • Multiple selection: Checks if the value exists in the selected values array
Parameters
$optionValue : mixed

The option value to check against selected value(s)

Return values
bool —

True if the option value is selected, false otherwise

render()

Get the view / contents that represent the component

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

The component view instance

generateId()

Generate HTML ID from component name

private generateId(string $name) : string

Converts the component name to a valid HTML ID by:

  • Converting to snake_case
  • Replacing dots with underscores for nested names
Parameters
$name : string

Component name (e.g., 'user.profile' or 'userName')

Return values
string —

Generated HTML ID (e.g., 'user_profile' or 'user_name')

generateVirtualSelectConfig()

Generate VirtualSelect.js configuration

private generateVirtualSelectConfig() : string

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

Tags
throws
InvalidArgumentException

When maxItemCount validation fails

Return values
string —

JSON configuration for VirtualSelect.js

processClasses()

Process CSS classes from various input formats

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

Combines the base CSS classes with user-provided classes. Handles both string and array inputs for flexibility.

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

CSS classes input (string, array, or null)

Return values
string —

Processed CSS classes string with base classes included

processOptions()

Process and normalize options from various input formats

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

Handles both Laravel Collections and plain arrays. Optionally sorts the options alphabetically for consistent display.

Parameters
$options : array<string|int, mixed>|Collection

Raw options input (array or Laravel Collection)

$sort : bool = false

Whether to sort the options alphabetically (default: false)

Return values
array<string|int, mixed> —

Processed options array ready for use in the component

Search results