Elemental.DataInput.Dropdown (elemental v0.3.1)
An abstraction around DaisyUI's dropdown.
Think of it as a more advanced Elemental.DataInput.Select
with support for
multi-select and searching out of the box.
This is implement in a manner that works drop-in in forms and uses only dead/stateless components with minimal JavaScript.
Usage
Make sure in your application to include the required JavaScript hooks
required for the main behaviour, found in dropdown.js
.
See the hooks section for more details.
Most basic usage is done by simply passing it options
<.dropdown options={["Foo", "Bar"]}/>
See dropdown/1
for details on the support properties and their behaviour.
JavaScript hooks
This implementation requires JavaScript hooks for it's main behaviour, utilizes 3 main hooks
ElementalDropdownSearch
implementing filtering/search behaviour when enabled.ElementalDropdownSingleItem
implementing prompt changes when using single item mode.ElementalDropdownMultiItem
implementing prompt changes when using multi item mode.
Implementation considerations
The component is implemented as a dead/stateless component as to simplify it's usage and avoid complexities associated with live/stateful components.
This comes from my dissatisfaction with implementations I found which have behaviours that I kept finding to be non-obvious and odd, from how they interact with events sent to parent vs themselves, along with how they handle their states.
Additionally the implementation aims to be drop-in compatible with forms in general as well as how forms are handled in Phoenix/LiveView without requiring much fuss.
The behaviour relies heavily on the provided minimal JavaScript hooks, as well as relying on native form behaviours with how forms deal with radio buttons and checkboxes.
Summary
Functions
The primary dropdown component.
Functions
The primary dropdown component.
This dropdown attempts to provide a fully featured dropdown/select element with native support for searching along with multiple select mode out of the box.
The API provided here works drop-in with Elemental's select component (see
Elemental.DataInput.Select
).
Select compatibility
While this component provides 1-1 API compatibility the the more simpler
Elemental.DataInput.Select.select/1
, augmenting it with additional features
and interactivity, there's the caveat that it does not yet
support option groups.
Attributes
options
(:list
) (required) - The list of values to select between. This is required to either be a list of strings, or a list of string tuples.List item types
- If given as a list of strings (
[String.t]
) each option will use that value as both it's label and value sent to from the dropdown. - If give as a list of tuples (
[{String.t, String.t}]
), those tuples are expected to be two strings, the first being the label to use, while the second is expected to be the value to send from the dropdown. - Mixing the two forms is allowed.
- If given as a list of strings (
prompt
(:string
) - The prompt to display for the the dropdown.This value is replaced when a selection is made with the selected item's label (requires JavaScript enabled in the browser).
Defaults to
nil
.name
(:string
) - The name of the dropdown, if not given a random value is selected.value
(:any
) - A value that is selected currently by the component.Useful for either preselecting items or to maintaining selected items state across rerenders.
Type
- The type is required to either be a single string or a list of strings, the values of it should correspond to the value (not label) of the options (if using a list of strings then it's the same as label).
- If the type is single select and if the value is a list of more than one item this will raise an error.
Defaults to
nil
.multi
(:boolean
) - To enable selection of multiple values, passed to consumer as a list. Defaults tofalse
.multiple
(:boolean
) - Only present for compatibility, if true enablesmulti
. Defaults tofalse
.searchable
(:boolean
) - To enable searching the options of the dropdown.Search is performed by looking through the labels for the given input as substring to match on, if it doesn't match the option is disabled, deselected, and hidden.
Notes:
- Search is case-insensitive.
- This features JavaScript enabled in the browser along with Hooks enabled.
Defaults to
false
.searchable-inline
(:boolean
) - To enable inlining of the search field for the dropdown.Implies
searchable
if enabled.Defaults to
false
.align
(:string
) - Specify the alignment for the dropdown. Defaults to"start"
.from
(:string
) - Specify where the dropdown will appear from. Defaults to"bottom"
.hover
(:boolean
) - To enable opening the dropdown on hover. Defaults tofalse
.open
(:boolean
) - To open the dropdown immediately. Defaults tofalse
.color
(:string
) - The dropdown prompt container color.Must be one of"ghost"
,"neutral"
,"primary"
,"secondary"
,"accent"
,"info"
,"success"
,"warning"
, or"error"
.size
(:string
) - The dropdown prompt container size.Must be one of"xs"
,"sm"
,"md"
,"lg"
, or"xl"
.class
(:string
) - Additional CSS classes to pass to the dropdown.Those will be applied to the the dropdown prompt container since it's the "visible"/"interactive" bit of the dropdown.
Defaults to
nil
.Global attributes are accepted.