Documentation

SelectGrid extends Component
in package

SelectGrid Laravel Blade Component

A visual grid-based selection component that presents options as clickable cards arranged in a customizable grid layout. Perfect for image-based selections, product choices, or any scenario where visual representation enhances user experience. Supports both single and multiple selection modes with responsive grid layouts.

Features:

  • Visual grid layout with customizable dimensions
  • Single or multiple selection support
  • Image/icon support for each option
  • Responsive grid structure
  • Automatic label generation from name
  • Collection and array options support
  • Customizable option width and grid rows
  • Form validation integration
  • Livewire real-time updates
  • Bulma CSS framework integration
  • Mobile-friendly responsive design

Grid Layout: The component supports flexible grid layouts by specifying either rows or columns:

  • Specify gridRows: component calculates columns automatically
  • Specify gridCols: component calculates rows automatically
  • If neither specified, defaults to 1 row with auto-calculated columns Each grid item can display:
  • Visual content (image, icon, or styled content)
  • Label text
  • Selection state indicators

Option Structure: Each option should contain:

  • 'value': The form value when selected
  • 'label': Display text for the option
  • 'url': Optional image/icon URL for visual representation
  • 'color': Optional CSS color value for color swatch display (either url or color should be provided)
Tags
author

V360

version
1.0.0
since
2025-12-23
example

<x-vform-select-grid name="theme_color" :options="[ ['value' => 'blue', 'label' => 'Ocean Blue', 'color' => '#3498db'], ['value' => 'green', 'label' => 'Forest Green', 'color' => '#2ecc71'], ['value' => 'red', 'label' => 'Crimson Red', 'color' => '#e74c3c'] ]" :multiple="false" :optionWidth="120" :gridCols="3" />

example

<x-vform-select-grid name="features" :options="[ ['value' => 'feature1', 'label' => 'Premium', 'color' => '#f39c12'], ['value' => 'feature2', 'label' => 'Logo', 'url' => '/icons/logo.png'], ['value' => 'feature3', 'label' => 'Custom', 'color' => '#9b59b6'] ]" :multiple="true" label="Select Features" hint="Choose multiple features for your product" :optionWidth="150" :gridRows="3" />

example

<x-vform-select-grid name="avatar" :options="[ ['value' => 'avatar1', 'label' => 'Avatar 1', 'url' => '/avatars/1.png'], ['value' => 'avatar2', 'label' => 'Avatar 2', 'url' => '/avatars/2.png'], ['value' => 'avatar3', 'label' => 'Avatar 3', 'url' => '/avatars/3.png'], ['value' => 'avatar4', 'label' => 'Avatar 4', 'url' => '/avatars/4.png'] ]" label="Choose Avatar" :multiple="false" :optionWidth="200" :gridRows="2" wire:model="selectedAvatar" />

Table of Contents

$gridCols  : int|null
$gridRows  : int|null
$hint  : string|null
$id  : string|null
$label  : string|null|false
$multiple  : bool
$name  : string
$options  : Collection|array<string|int, mixed>
$optionWidth  : int
$value  : array<string|int, mixed>|null
__construct()  : mixed
Construct SelectGrid component
getColumnsPerRow()  : int
Get the number of columns for the grid
getProcessedLabel()  : string|false
Get the processed label for display
getRowsPerGrid()  : int
Get the number of rows for the grid
isSelected()  : bool
Check if a value is selected
render()  : View|Closure|string
Get the view / contents that represent the component.
generateId()  : string
Generate HTML ID from component name

Properties

$options

public Collection|array<string|int, mixed> $options

$value

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

Methods

__construct()

Construct SelectGrid component

public __construct(string $name, Collection|array<string|int, mixed> $options[, string|null $id = null ][, array<string|int, mixed>|null $value = null ][, string|null|false $label = null ][, bool $multiple = false ][, int $optionWidth = 150 ][, int|null $gridRows = null ][, int|null $gridCols = null ][, string|null $hint = null ]) : mixed
Parameters
$name : string

Name of the select input

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

Options for the select grid. Each item should have: [value, label, url?, color?]

$id : string|null = null

Id of the select input (auto-generated if null)

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

Initial selected value(s)

$label : string|null|false = null

Label for the select input. False to hide, null for auto-generated

$multiple : bool = false

Whether multiple selection is allowed

$optionWidth : int = 150

Width of each option in the grid (in pixels)

$gridRows : int|null = null

Number of rows in the grid (computed if gridCols is provided)

$gridCols : int|null = null

Number of columns in the grid (computed if gridRows is provided)

$hint : string|null = null

Optional hint text to display below the component

Return values
mixed —

getColumnsPerRow()

Get the number of columns for the grid

public getColumnsPerRow() : int

Returns the number of columns based on:

  • If gridCols is specified, returns that value
  • If gridRows is specified, calculates columns from total options divided by rows
  • Ensures at least 1 column is returned
Return values
int —

The number of columns in the grid

getProcessedLabel()

Get the processed label for display

public getProcessedLabel() : string|false

Processes the label based on the label property:

  • If false: returns false (no label)
  • If null: auto-generates from name (snake_case to Title Case)
  • Otherwise: returns the provided label string
Return values
string|false —

The processed label string or false if no label should be shown

getRowsPerGrid()

Get the number of rows for the grid

public getRowsPerGrid() : int

Returns the number of rows based on:

  • If gridRows is specified, returns that value
  • If gridCols is specified, calculates rows from total options divided by columns
  • Ensures at least 1 row is returned
Return values
int —

The number of rows in the grid

isSelected()

Check if a value is selected

public isSelected(mixed $optionValue) : bool

Determines if the given option value is currently selected by checking if it exists in the component's value array.

Parameters
$optionValue : mixed

The option value to check for selection

Return values
bool —

True if the 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')

Search results