Upgrade guide

#Legacy compatibility component

The new structure of this package is quite different to how it was structured in previous versions.

The new structure is to compose small, customisable components, to create the autocomplete that suits your needs.

Where as the previous structure was one giant blade component that you passed a lot of data and props into.

For those that may be using this package in their (sometimes large) apps, we don't want to cause too many problems when upgrading. Because of this we have a legacy compatibility component to aide in upgrading to the latest version of this package without having to change all usages of the autocomplete component to the new structure straight away.

To update an existing up to use the legacy compatibility component, search for either x-autocomplete or x-lwa::autocomplete (depending on if you have global components enabled or not) and replace them with either x-autocomplete-legacy or x-lwa::autocomplete-legacy.

For full details on the legacy compatibility component, see the docs page [[Legacy compatibility component]].

Listed below are some further changes between the current and previous version.

#Removed dynamic components

In the previous version, each of the internal components were dynamic which allowed a user to override it so they could apply their own styles.

The new version exposes all the components, which allows more flexible customisation.

As such the following dynamic components have been removed:

• outer-container
• input
• clear-button
• dropdown
• loading
• results-container
• prompt
• results-list
• no-results

To ease upgrading, the following dynamic components still exist when used with the new legacy component:

• result-row
• add-new-row

#Removed events

If you were listening for the following events that were being dispatched by the component, they are no longer available:

• autocomplete-input
• autocomplete-selected-object

If you were dispatching the following events to update the component from the outside, they are no longer available:

• autocomplete-set

We would recommend that if you need any of the above, that you implement them manually using Alpine on one of the autocomplete components. For example x-on:input="$dispatch('{{ $name}}-input', $event.target.value)"

#Config changes

The following config changes have been made:

#File renamed

The config file has been renamed from config/autocomplete.php to config/livewire-autocomplete.php.

#Options renamed

options have been renamed to legacy_options and only works with the <x-autocomplete-legacy> component and doesn't work for any of the new components.

#Components renamed

components have been renamed to legacy_components and all have been removed except for result-row and add-new-row.

#Old config example

The old config looked like this:

return [
    'options' => [
        'id' => 'id',
        'text' => 'text',
        'auto-select' => true,
        'allow-new' => true,
        'load-once-on-focus' => true,
        'inline' => false,
        'inline-styles' => 'relative',
        'overlay-styles' => 'absolute z-30',
        'result-focus-styles' => 'bg-blue-500',
    ],
 
    'components' => [
        'outer-container' => 'outer-container',
        'input' => 'input',
        'clear-button' => 'clear-button',
        'dropdown' => 'dropdown',
        'loading' => 'loading',
        'results-container' => 'results-container',
        'prompt' => 'prompt',
        'results-list' => 'results-list',
        'add-new-row' => 'add-new-row',
        'result-row' => 'result-row',
        'no-results' => 'no-results',
    ],
 
    // Set this to true if you would prefer it to use the global namespace <x-autocomplete />
    'use_global_namespace' => false,
 
    'inline-scripts' => true,
];

#New config example

The new config looks like this:

return [
    /*
     * Set this to `true` if you want to use the global namespace
     * `<x-autocomplete />` or `false` if you want to use the
     * package namespace `<x-lwa::autocomplete />`
     *
     * This is set to true by default
     */
    'use_global_namespace' => true,
 
    'inline_scripts' => true,
 
    // Only to be used for apps that are using the legacy version of the package
    'legacy_options' => [],
 
    // Only to be used for apps that are using the legacy version of the package
    'legacy_components' => [],
];