Livewire Select2

Livewire Select2 turns a <select> in a Livewire component into a Select2 widget that stays in sync with the component. Put data-pharaonic="select2" and wire:model on the select, load one Blade directive, and the widget follows the property in both directions: what the user picks reaches the component, and what the server sets shows in the widget. It is built on Livewire Assistant, which finds the elements, binds each one to the component that owns it, and cleans them up when Livewire removes them.

#Installation

Install the package with Composer, keep jQuery and Select2 on the page, and load the scripts once.

#Requirements

• PHP 7.4 (Livewire 1 only installs on PHP 7)
• Laravel 7.30+ or 8.75+
• Livewire 1.3.0 to 1.3.9, except 1.3.7 (see Compatibility)
• jQuery and Select2 4, loaded by your application
• A modern browser (ES2019); Internet Explorer is not supported

#Composer Installation

composer require pharaonic/livewire-select2

Composer also installs pharaonic/livewire-assistant. Laravel discovers both service providers automatically. There is nothing to publish and no configuration file.

composer config --json policy.advisories.ignore '{"livewire/livewire": "No fixed release within Livewire 1.", "laravel/framework": "No fixed release within this Laravel major.", "league/commonmark": "No fixed release within this Laravel major.", "league/flysystem": "No fixed release within this Laravel major."}'

#Load the Scripts

Load jQuery and Select2 the way you already do, then add @livewireSelect2Scripts to your layout. It can go before or after @livewireScripts.

 1<head>
 2    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/select2.min.css">
 3    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
 4    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/select2.min.js"></script>
 5    @livewireStyles
 6</head>
 7<body>
 8    {{ $slot }}
 9 
10    @livewireScripts
11    @livewireSelect2Scripts
12</body>

The directive renders two <script> tags: the Livewire Assistant runtime and this integration. Each is rendered once per page, even when layouts, partials, and @livewireAssistantScripts ask for it again.

1<script src="https://example.com/pharaonic/livewire-assistant/assistant.js?id=3f9a1c2b7d4e5f60" data-turbolinks-eval="false"></script>
2<script src="https://example.com/pharaonic/livewire-select2/select2.js?id=0d8eee40cb71f6d7" data-turbolinks-eval="false"></script>

jQuery and Select2 are read from window.jQuery when a select mounts, not when the script loads, so their order relative to the directive does not matter. If they are still missing when the page has finished loading, the select is reported as mount-failed with the select2-missing cause.

#Vite and Other Bundlers

When jQuery and Select2 come from npm, expose jQuery on window and attach Select2 to that same jQuery. The package never uses $, so you do not need a global $.

1import jQuery from 'jquery'
2import select2 from 'select2'
3 
4window.jQuery = jQuery
5select2()

Keep @livewireSelect2Scripts in the layout, or import the ES modules instead (see below).

#Content Security Policy

Pass a nonce when your CSP uses one. Both tags get it, escaped.

1@livewireSelect2Scripts(['nonce' => $cspNonce])

nonce is the only option. An unknown option or a non-string nonce throws an InvalidArgumentException while the view renders. The scripts never use eval or inline code.

#How the Script Is Served

The route serves dist/livewire-select2.js from the installed package, without session or cookies. The id query value is a hash of the file: a matching id is cached for a year, anything else is served with no-cache. After composer update the hash changes, so browsers fetch the new script on the next page load. Nothing needs publishing, and the route works with php artisan route:cache.

#ES Module

If you bundle your JavaScript, import the ES modules from the Composer packages instead of using the directive. Import the Assistant too: the integration registers with it but never loads it.

1import jQuery from 'jquery'
2import select2 from 'select2'
3import '../../vendor/pharaonic/livewire-assistant/dist/livewire-assistant.esm.js'
4import { define } from '../../vendor/pharaonic/livewire-select2/dist/livewire-select2.esm.js'
5 
6window.jQuery = jQuery
7select2()

The ES module and the browser build share one integration per page, so loading both is harmless.

#Basic Usage

A Select2 field is a normal <select> with data-pharaonic="select2" and wire:model, wrapped in wire:ignore.

#The Component

 1<?php
 2 
 3namespace App\Http\Livewire;
 4 
 5use Livewire\Component;
 6 
 7class Profile extends Component
 8{
 9    public $country = '2';
10 
11    public $languages = ['ar'];
12 
13    public function render()
14    {
15        return view('livewire.profile');
16    }
17}

#The View

 1<div>
 2    <div wire:ignore>
 3        <select data-pharaonic="select2" wire:model="country" data-placeholder="Choose a country" data-clear>
 4            <option value=""></option>
 5            <option value="1">Egypt</option>
 6            <option value="2">Jordan</option>
 7        </select>
 8    </div>
 9 
10    <div wire:ignore>
11        <select multiple data-pharaonic="select2" wire:model="languages">
12            <option value="ar">Arabic</option>
13            <option value="en">English</option>
14        </select>
15    </div>
16</div>

That is all. The first select shows Jordan; picking Egypt sets $country to "1"; $this->country = '2' on the server selects Jordan again. The second select holds an array.

#Why wire:ignore

Livewire updates a component's HTML after each request to match the server. Select2 hides the <select> and adds its own markup next to it, which that update would remove. wire:ignore tells Livewire to leave the block alone, so the widget survives every request. The package keeps the value in sync through the component, not through the HTML.

A select can also live outside wire:ignore. The package then rebuilds the widget after each Livewire update, which is useful when the server changes its options. See Dynamic Selects.

#The Attributes

Without wire:model or data-property, the select becomes a Select2 widget that is not bound to anything.

#Binding

The package binds a select to one component property, in both directions.

#wire:model or data-property

The property comes from wire:model on the select, or from data-property. When both are present, data-property wins.

1<select data-pharaonic="select2" wire:model="country">...</select>
2<select data-pharaonic="select2" data-property="address.country_id">...</select>

Both accept a property name or a dot path (address.city, rows.2.product).

#Modifiers on Livewire 1

Livewire 1 has no deferred updates, so every write is sent right away. wire:model.lazy and wire:model.debounce.500ms are accepted and behave like wire:model: a Select2 choice is a single change, so there is nothing to debounce.

#How Values Move

• Initial value. When the select mounts, it shows the property's current value.
• User to server. A Select2 change sends the new value to the property in a Livewire request.
• Server to widget. When a Livewire update changes the property, from an action, a lifecycle hook, or another field, the widget selects the new value.
• No echo. Values the server sets are shown without being sent back, and a choice equal to the current value sends nothing.

#Value Types

Select2 works with strings. The package converts at the boundary:

What the user picks is sent as a string, or an array of strings for a multiple select. Cast it in the component if you need integers.

#Tags

With data-tags, users can type new values. Values in the property that have no <option>, such as tags saved earlier, get one when they are shown, so they appear on the first render.

1<div wire:ignore>
2    <select multiple data-pharaonic="select2" wire:model="labels" data-tags>
3        <option value="urgent">urgent</option>
4    </select>
5</div>

#Reacting to Changes

wire:change on the select runs after the new value is written, so the action sees it:

1<div wire:ignore>
2    <select data-pharaonic="select2" wire:model="country" wire:change="countryChanged">...</select>
3</div>

Select2 itself never fires the native change event; the package fires one for selects that have wire:change. Change handlers you attach with jQuery receive that event too, so on these selects they run twice. An updated hook in the component needs no event at all:

1public function updatedCountry($value)
2{
3    $this->city = null;
4}

#Options

There are three ways to configure Select2, from the simplest:

1. the package's shorthand attributes, for the most common options;
2. Select2's own data-* attributes;
3. data-options, a JSON object, for everything else.

#Shorthand Attributes

1<select data-pharaonic="select2" wire:model="country" data-placeholder="Choose a country" data-clear data-search-off>

A shorthand is on when the attribute is present, with or without a value. data-clear="false" turns it off, which helps when Blade decides: data-clear="{{ $nullable ? 'true' : 'false' }}".

Select2 shows the clear button only when there is a placeholder. When you turn data-clear on without a placeholder, the package sets an empty one, so the button appears without adding text.

Use data-parent for selects inside modals, so the dropdown opens inside the modal and its search field can take focus. Without a value, it picks the closest .modal (Bootstrap), <dialog>, or [role="dialog"]:

1<div class="modal" id="edit-modal">
2    <div wire:ignore>
3        <select data-pharaonic="select2" wire:model="type" data-parent>...</select>
4    </div>
5</div>

With a CSS selector, it uses that element instead: data-parent="#edit-modal". When nothing matches, the dropdown opens in body as usual.

#Select2's Own data-* Attributes

Select2 reads any option from a data-* attribute, with the option name in kebab case. These need no help from the package:

#data-options

Anything else goes in data-options as a JSON object:

1<select data-pharaonic="select2" wire:model="labels" multiple data-options='{"closeOnSelect": false, "tokenSeparators": [","]}'>

Use single quotes around the attribute so the JSON can use double quotes. In Blade you can build it from PHP:

1<select data-pharaonic="select2" wire:model="country" data-options='@json(["placeholder" => __("Choose a country"), "allowClear" => true])'>

data-options can also hold dropdownParent as a selector. Invalid JSON, or JSON that is not an object, is reported as invalid-options and the select is not mounted.

#Which Wins

data-options overrides the shorthand attributes. Select2's own data-* attributes override both, because Select2 applies them last. Set each option in one place.

#Functions in Options

Some Select2 options are JavaScript functions, which attributes cannot hold. Define the function once in JavaScript and use its name in data-options. See Templates and Callbacks.

#Changing Options

Inside wire:ignore, Livewire never changes the select, so new attributes from the server are not applied. To change options or the list of <option> elements, let Livewire replace the block with a new wire:key. See Dynamic Selects.

#Templates and Callbacks

#Images Without JavaScript

Add data-image to an <option> to show an image before its text, in the dropdown and in the selection:

1<div wire:ignore>
2    <select data-pharaonic="select2" wire:model="country">
3        @foreach ($countries as $country)
4            <option value="{{ $country->id }}" data-image="{{ asset('flags/'.$country->code.'.svg') }}">{{ $country->name }}</option>
5        @endforeach
6    </select>
7</div>

The image is 1.25em high, aligned with the text, and has the pharaonic-select2-image class for your own styling. Options without data-image show their text as usual. A select with its own templateResult or templateSelection uses those instead.

#Your Own Templates

Select2 options such as templateResult take functions. Define a function with a name, then use the name in data-template or data-options.

#define(name, callback)

 1Pharaonic.select2.define('flag', (state) => {
 2    if (!state.element) {
 3        return state.text
 4    }
 5 
 6    const span = document.createElement('span')
 7 
 8    span.textContent = `${state.element.dataset.flag} ${state.text}`
 9 
10    return span
11})

1<div wire:ignore>
2    <select data-pharaonic="select2" wire:model="country" data-template="flag">
3        <option value="eg" data-flag="🇪🇬">Egypt</option>
4        <option value="jo" data-flag="🇯🇴">Jordan</option>
5    </select>
6</div>

data-template sets both templateResult and templateSelection. To use different functions, name them in data-options, which overrides data-template:

1<select data-pharaonic="select2" wire:model="country" data-template="flag" data-options='{"templateSelection": "flagOnly"}'>

• A name starts with a letter or digit and continues with letters, digits, ., :, _ or -. Anything else, or a callback that is not a function, throws an error with the code invalid-function.
• Defining the same function under the same name again does nothing. A different function under a taken name throws function-conflict.
• With a bundler, import define from the ES module instead of using window.Pharaonic.select2.

#Options That Accept a Name

Any other option keeps its JSON value. ajax.url stays a string.

#Load Order

Call define after @livewireSelect2Scripts has loaded, for example in a deferred or module script, or import it from the ES module. A select that uses a name that is not defined yet waits: a console warning names the function once, and the select mounts as soon as define is called.

#Remote Data

1Pharaonic.select2.define('countries', (data) => ({
2    results: data.map((country) => ({ id: country.id, text: country.name })),
3}))

1<select data-pharaonic="select2" wire:model="country_id" data-options='{"ajax": {"url": "/api/countries", "dataType": "json", "processResults": "countries"}}'>
2    @if ($country)
3        <option value="{{ $country->id }}" selected>{{ $country->name }}</option>
4    @endif
5</select>

With remote data, Select2 can only show a value that has an <option>. Render the selected one in Blade, as above.

#Dynamic Selects

Livewire adds, removes, and re-renders elements. The package follows it.

#Selects Livewire Adds or Removes

Selects that appear after a Livewire update, such as a new row from wire:click="addRow", mount and bind after that update. Selects that disappear are cleaned up: their handlers are removed and Select2 is destroyed.

1@foreach ($rows as $index => $row)
2    <div wire:key="row-{{ $index }}">
3        <div wire:ignore>
4            <select data-pharaonic="select2" wire:model="rows.{{ $index }}.product">...</select>
5        </div>
6    </div>
7@endforeach
8 
9<button wire:click="addRow">Add row</button>

#Dependent Selects

When one select decides the options of another, the second select needs its new <option> list from the server. There are two ways.

A new wire:key per parent value. Livewire replaces the ignored block when its key changes. The old widget is cleaned up and the new select mounts with the new options.

 1<div wire:ignore>
 2    <select data-pharaonic="select2" wire:model="level">...</select>
 3</div>
 4 
 5<div wire:ignore wire:key="group-{{ $level }}">
 6    <select data-pharaonic="select2" wire:model="group">
 7        <option value="">Choose a group</option>
 8        @foreach ($groups as $id => $name)
 9            <option value="{{ $id }}">{{ $name }}</option>
10        @endforeach
11    </select>
12</div>

No wire:ignore. Livewire updates the select, and the package rebuilds the widget after each update.

1<div>
2    <select data-pharaonic="select2" wire:model="group">...</select>
3</div>

The first way keeps the widget untouched by unrelated requests. The second is simpler, but every request that re-renders the component rebuilds the widget and closes an open dropdown.

Reset the child property when the parent changes:

1public function updatedLevel()
2{
3    $this->group = '';
4}

#Nested Components and Many Selects

Each select binds to the closest Livewire component around it. A select in a nested component writes to that component, never to the parent. Any number of selects can share a page.

data-component-id binds a select to a specific component wherever it is. In a Livewire 1 view the id is $this->id. An empty value means the closest component.

#Selects You Add Yourself

Selects you add with JavaScript, outside a Livewire update, need one call:

1Pharaonic.assistant.scan(container)     // mounts the selects in container
2Pharaonic.assistant.destroy(container)  // cleans them up

#Turbolinks

Widgets are cleaned up before Turbolinks caches a page and mounted again when it comes back.

#API Reference

#Markup

On <option>:

#Browser API

Available as window.Pharaonic.select2 and as named exports of dist/livewire-select2.esm.js.

Deprecated aliases, on window.Pharaonic.Select2:

#Events

#Error Codes

#Laravel

#Compatibility

Every combination below installs with Composer and passes the PHP suite and the real-browser suite (real Livewire 1 components, the real Livewire Assistant runtime, jQuery, and Select2, driven in real browsers) with lowest and highest dependencies.

The browser suite uses jQuery 4 and Select2 4.1.

#Why PHP 7.4

Every Livewire 1 release requires PHP 7. PHP 7.4 is the oldest PHP the package's test and analysis tools run on.

#What Livewire 1 Cannot Do

Livewire 1 has no deferred updates, so every write is live, whatever the wire:model modifiers.

#Examples

#1. Edit Form in a Modal

The server fills the form when the modal opens; the select shows the saved value and opens its dropdown inside the modal.

 1<?php
 2 
 3namespace App\Http\Livewire;
 4 
 5use App\Models\Category;
 6use App\Models\Item;
 7use Livewire\Component;
 8 
 9class Items extends Component
10{
11    public $editing = false;
12 
13    public $itemId;
14 
15    public $category_id;
16 
17    public function edit($id)
18    {
19        $item = Item::findOrFail($id);
20 
21        $this->itemId = $item->id;
22        $this->category_id = $item->category_id;
23        $this->editing = true;
24    }
25 
26    public function render()
27    {
28        return view('livewire.items', ['categories' => Category::pluck('name', 'id')]);
29    }
30}

 1<div>
 2    <div class="modal" style="display: {{ $editing ? 'block' : 'none' }}">
 3        <div wire:ignore>
 4            <select data-pharaonic="select2" wire:model="category_id" data-placeholder="Category" data-clear data-parent>
 5                <option value=""></option>
 6                @foreach ($categories as $id => $name)
 7                    <option value="{{ $id }}">{{ $name }}</option>
 8                @endforeach
 9            </select>
10        </div>
11    </div>
12</div>

#2. Country and City

The city list depends on the country. A new wire:key replaces the city select whenever the country changes.

 1public $country_id = '';
 2 
 3public $city_id = '';
 4 
 5public function updatedCountryId()
 6{
 7    $this->city_id = '';
 8}
 9 
10public function render()
11{
12    return view('livewire.address', [
13        'countries' => Country::pluck('name', 'id'),
14        'cities' => City::where('country_id', $this->country_id)->pluck('name', 'id'),
15    ]);
16}

 1<div>
 2    <div wire:ignore>
 3        <select data-pharaonic="select2" wire:model="country_id">
 4            <option value="">Country</option>
 5            @foreach ($countries as $id => $name)
 6                <option value="{{ $id }}">{{ $name }}</option>
 7            @endforeach
 8        </select>
 9    </div>
10 
11    <div wire:ignore wire:key="cities-{{ $country_id }}">
12        <select data-pharaonic="select2" wire:model="city_id">
13            <option value="">City</option>
14            @foreach ($cities as $id => $name)
15                <option value="{{ $id }}">{{ $name }}</option>
16            @endforeach
17        </select>
18    </div>
19</div>

#3. Invoice Rows

Each row has its own select bound to its own array item.

 1<div>
 2    @foreach ($rows as $index => $row)
 3        <div wire:key="row-{{ $index }}">
 4            <div wire:ignore>
 5                <select data-pharaonic="select2" wire:model="rows.{{ $index }}.product_id">
 6                    <option value="">Product</option>
 7                    @foreach ($products as $id => $name)
 8                        <option value="{{ $id }}">{{ $name }}</option>
 9                    @endforeach
10                </select>
11            </div>
12            <button wire:click="removeRow({{ $index }})">Remove</button>
13        </div>
14    @endforeach
15 
16    <button wire:click="addRow">Add row</button>
17</div>

#4. Tags

Users pick existing tags or type new ones; saved tags show on load even without an option.

1<div wire:ignore>
2    <select multiple data-pharaonic="select2" wire:model="tags" data-tags data-options='{"tokenSeparators": [","]}'>
3        @foreach ($suggestions as $tag)
4            <option value="{{ $tag }}">{{ $tag }}</option>
5        @endforeach
6    </select>
7</div>

#Troubleshooting

#Nothing happens and there is no widget

Check the console. select2-missing means jQuery or Select2 is not on window.jQuery: load them, or with a bundler set window.jQuery and call select2() (see Installation). Make sure @livewireSelect2Scripts is on the page.

#"$ is not a function"

The package never uses $; it reads window.jQuery when a select mounts. The error comes from code that expects a global $. With a bundler, set window.jQuery as shown in Installation.

#The widget disappears or resets after a request

The select is outside wire:ignore and the package rebuilds it after each update, or Livewire replaced the block. Wrap the select in wire:ignore unless you want the server to change its options.

#New options from the server do not appear

Inside wire:ignore, Livewire never changes the select. Give the ignored block a wire:key that changes with the data, or remove wire:ignore. See Dependent Selects.

#My jQuery change handler runs twice

The select has wire:change. Select2 fires its own jQuery change event, and the package fires a native one so wire:change runs. Use wire:change or the updated hook instead of the jQuery handler, or remove wire:change.

#The value is a string, but my property is an integer

Select2 works with strings. Cast in the component, for example in an updated hook.

#The dropdown opens behind a modal, or its search field cannot take focus

Add data-parent to the select. It opens the dropdown in the closest .modal, <dialog>, or [role="dialog"]; give it a selector when the modal is something else.

#A select in a nested component updates the parent

Remove a data-component-id that names the parent, or leave the attribute out: the closest component is used.

#Composer refuses to install Livewire 1 or Laravel 7 or 8

Those releases have unfixed security advisories. See the warning in Installation.