Skip to content

Searchable dropdown component Laravel Package

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE
MIT
LICENSE.md
Notifications You must be signed in to change notification settings

teofanis/searchable-dropdown

Repository files navigation

Searchable Dropdown

Latest Version on Packagist Build Status Quality Score Total Downloads

Searchable dropdown is a dropdown component built with Alpine JS, tailwind and Blade components. It can be used as a normal dropdown or a multiple selection dropdown.

Installation

You can install the package via composer:

composer require teofanis/searchable-dropdown

Publish the dropdowns' config and asset files

php artisan vendor:publish --tag=searchable-dropdown-config
php artisan vendor:publish --tag=searchable-dropdown-assets

Finally add the dropdown styles and scripts in the head section of your layout file.

@searchableDropdownStyles
@searchableDropdownScripts

Usage

Here's an example of how you could use the dropdown inside your blade views.

#Simple select & Multiselect

dropdown

-Select

<x-searchable-dropdown
    name="pizzas"
    entangle="pizzaType"
    :context="$this"
    :data="$pizzas"
    in_live_wire="true"
    no_results_message="No Pizzas found"
    placheholder="Choose your Pizza"
    search_placeholder="Search for pizzas..."
    />

-Multiselect

<x-searchable-dropdown
    name="toppings"
    entangle="chosenToppings"
    :context="$this"
    :data="$toppings"
    in_live_wire="true"
    :multiselect="true"
    no_results_message="No toppings found"
    placheholder="Select your toppings"
    search_placeholder="Search toppings..."
    />

#Customization & Props

Props Required Context Description Type Example
name yes any Used as "name" attribute on input fields and used to internally by the dropdown string name="pizzaOptions"
entangle Required within Livewire components Livewire The dropdown will share its state with the "entangled" property of the Livewire components its rendered in. string entangle="pizzaToppings"
context Required within Livewire components Livewire The dropdown will use the context to setup the state-sharing with livewire component. (Won't be required in future release) LW :context="$this"
inLivewire Required within Livewire components Livewire Similarly to the context prop, this will be used in the initial setup of the component. (Won't be required in future release) boolean :in_live_wire="true"
value no any Used as any value attribute on input fields string/array value="old('name')" || :value="[1,2,3]"
data yes any Populates the dropdown list, collection keys will be returned for selections and values will be displayed. Collection :data="dataProvider()"
xModel no Alpine An option prop when you want to bind an apline js x-data field as a model of the dropdown. string x_model="modelName"
multiselect multiselect any Used to behave like a multiple option dropdown or a single option dropdown boolean :multiselect="true"
alignListItems no any Aligns the text on the dropdown list. You can pass a tailwind class for text-alignment e.g(text-left, text-right, text-center etc.) string align_items="text-left"
disabled no any Disable the dropdown interaction boolean :disabled="true"
label no any Displays the prop value as as label of the dropdown string label="My Dropdown Label"
placeholder no any Sets the placeholder text for the dropdown string placeholder="My Placeholder Text"
searchFieldPlaceholder no any Sets the placeholder for the search field string search_field_placeholder="My Search field Placeholder"
noResultsMessage no any Sets the message of the no-results block when filtering string no_results_message="No options found"

Most props have default values set in config/searchable-dropdown-config.php that serve as a base for most use-cases.

Placeholder Defaults
   
'placeholders' => [
       'default-no-results-message' => 'No Results Found',
       'default-placeholder' => 'Select an option',
       'default-search-placeholder' => 'Search...',
   ]
   
Setting Defaults
     'settings' => [
       'default-is-multiselect' => false,
       'default-is-in-livewire' => false, 
       'default-list-item-alignment' => 'text-left'
   ],
   
Theme Styles

With the theme styles, you can do some small adjustments on color pallete of the dropdown as well as style the wrapper, label or button all using tailwind classes

   'styles' => [
       'theme' => [
           'default-text-color' => 'text-gray-900',
           'default-primary-color' => 'indigo-600',
           'default-secondary-color' => 'white',
       ],
       'classes' => [ 
           'wrapper' => 'inline-block w-full rounded-md shadow-sm',
           'label' => 'block tracking-wide text-xs font-bold mb-4 char-style-medium cursor-pointer leading-none text-mbr_blue font-hairline',
           'button' => 'relative z-0 w-full py-2 pl-3 pr-10 text-left transition duration-150 ease-in-out bg-white border border-gray-300 rounded-md cursor-default focus:outline-none focus:shadow-outline-blue focus:border-blue-300 sm:text-sm sm:leading-5',
       ]
   ],
   

To Fully customize the look & feel of the dropdown, publish the packages' views.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.