This package supports Select2 JS library and Javaabu's select2-custom data attributes. To use Select2, you must use the select2 component instead of the standard select component. This will generate a select element with the select2-basic class applied.

<x-forms::select2 name="country" :options="$countries" />

Using Ajax

To load the select options from Ajax as you type, you must use the is-ajax attribute and provide an API url using the ajax-url attribute. When using Ajax, make sure the initial options include the current selected value.

<x-forms::form :model="$address">
    <x-forms::select2 name="country" :label="__('Country')" :options="Country::whereId(isset($address) ? $address->country_id : old('country'))" :ajax-url="route('api.countries.index')" is-ajax />
</x-forms::form>

You can use the id-field and name-field attributes to customize the fields that are used to retrieve the options in the API request.

Disabling allow clear

By default, all select2 elements will have the data-allow-clear option enabled which will show a button to clear the current selection. You can disabled this feature by setting allow-clear attribute to false.

<x-forms::select2 name="country" :options="$countries" :allow-clear="false" />

Hiding the search box

If you want to hide the search box for a select2 element, use the hide-search attribute. This would add data-minimum-results-for-search="Infinity" to the select element, which will disable the search feature.

<x-forms::select2 name="country" :options="$countries" hide-search />

Enabling tags

To enable the user to add their own options to the select, enable the tags feature of Select2 by using the tags attribute. When you use the tags option, any old values will automatically get added to the options if there's a validation error.

<x-forms::select2 name="categories" :options="$options" multiple tags />

Using Select2 inside a modal

When using a select2 element inside a modal, remember to use the parent-modal attribute to specify the selector of the modal to properly render the select2 element.

<x-modal id="your-modal">
    <x-forms::select2 name="country" :options="$countries" parent-modal="#your-modal" />
</x-modal>

Setting up a Select2 cascade

If you want to setup a cascade of selects that depends on each other, use the is-first attribute on the first select in the cascade and use the child attribute to specify its child select. Then on the child select, use the filter-field attribute to specify the field name that's used to filter the results in the API request.

Notice that here ajax-url is used without setting is-ajax to true. The reason for this is we want the options of the children elements to be loaded only when a parent element's selected value changes, but we don't want the children elements' options to change as we search inside their select2 search boxes.

<x-forms::form :model="$address">
    <x-forms::select2 name="country" :options="Country::query()" child="#state" is-first />

    <x-forms::select2 name="state" :options="State::whereCountryId($address->country?->id ?? null)" :ajax-url="route('api.states.index')" child="#city" filter-field="country" />

    <x-forms::select2 name="city" :options="City::whereStateId($address->state?->id ?? null)" :ajax-url="route('api.cities.index')" filter-field="state" relation />

    <x-forms::submit>Submit</x-forms::submit>
</x-forms::form>

You can use the fallback attribute to specify a text input that would be displayed instead of a select when a child select receives 0 options from the API. This will allow users to enter their own values if no options are available. When a fallback is active, its associated select will be disabled. Remember to add the fallback class to the fallback element.

<x-forms::form :model="$address">
    <x-forms::select2 name="country" :options="Country::query()" child="#state" is-first />

    <x-forms::select2 name="state" :options="State::whereCountryId($address->country?->id ?? null)" :ajax-url="route('api.states.index')" child="#city" filter-field="country" />

    <x-forms::select2 name="city" :options="City::whereStateId($address->state?->id ?? null)" :ajax-url="route('api.cities.index')" fallback="#city-name" filter-field="state" relation />
    
    <x-forms::text name="city" id="city-name" class="fallback" :placeholder="__('Write your own city name...')" />

    <x-forms::submit>Submit</x-forms::submit>
</x-forms::form>

Configuring a Select2 element to search from multiple URLs

You can configure a Select2 element to be able to search from multiple URLs, depending on the selected value of another select element.

Imagine you want to build a menu builder for your application, and you want to allow users to be able to select a menu item type (e.g. courses, job listings, employers) and then search for the items of that type.

You can do this by using the ajax-child and is-first attribute on the type select field, and then use is-ajax, ajax-url and selected-url attributes on the child select field.

@php
    $menu_item_types = ['jobs' => 'Jobs', 'employers' => 'Employers'];
    $urls = ['jobs' => 'https://example.com/api/jobs', 'employers' => 'https://example.com/api/employers'];
@endphp

<x-forms::select2
    name="post_type"
    :options="$menu_item_types"
    ajax-child="#model_id"
    is-first
    allow-clear
    placeholder="Nothing Selected"
/>

<x-forms::select2
    name="post_id"
    is-ajax
    :ajax-url="json_encode($urls)"
    placeholder="Select a post to link"
    allow-clear
    selected-url=""
/>