sporto / elm-select / Select

Select input with auto-complete

See a full example of the select input here

See a full example of the select input in multi mode here

See live demo here

Types


type alias RequiredConfig msg item =
{ filter : String -> List item -> Maybe (List item)
, toLabel : item -> String
, onSelect : Maybe item -> msg
, toMsg : Msg item -> msg 
}

Required initial configuration


type Config msg item

Opaque type that holds all the configuration


type State

Opaque type that holds the current state


type Msg item

Opaque type for internal library messages

Configuration

newConfig : RequiredConfig msg item -> Config msg item

Create a new configuration. This takes as RequiredConfig record.

withCustomInput : (String -> item) -> Config msg item -> Config msg item

Allow users to write a custom values (free text entry) You must provide a function that converst a String into an item

config
    |> Select.withCustomInput (\string -> item)

withCutoff : Basics.Int -> Config msg item -> Config msg item

Set the maxium number of items to show

config
    |> Select.withCutoff 6

withOnQuery : (String -> msg) -> Config msg item -> Config msg item

Add a callback for when the query changes.

config
    |> Select.withOnQuery OnQuery

withEmptySearch : Basics.Bool -> Config msg item -> Config msg item

Show results if the input is focused, but the query is empty. Similar to a dropdown, focusing on the input will show the menu.

Default is False.

Select.withEmptySearch True config

withTransformQuery : (String -> String) -> Config msg item -> Config msg item

Transform the input query before performing the search Return Nothing to prevent searching

transform : String -> Maybe String
transform query =
    if String.length query < 4 then
        Nothing
    else
        Just query

config
|> Select.withTransformQuery transform

withTransformInput : (String -> String) -> Config msg item -> Config msg item

Transform the input This can be used to restrict input to certain characters. Returning "" effectively disables input

transform : String -> String
transform input =
    ""

config
|> Select.withTransformInput transform

Configure Multi Select mode

withMultiSelection : Basics.Bool -> Config msg item -> Config msg item

Use a multi select instead of a single select.

withOnRemoveItem : (item -> msg) -> Config msg item -> Config msg item

Message to call when removing an individual item. Please note that without this option specified, you will not be able to remove an individual item from MultiSelect mode.

config
    |> Select.withOnRemoveItem OnRemoveItem

withMultiInputItemContainerAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the container of selected items.

config
    |> Select.withMultiInputItemContainerAttrs [ class "bg-white" ]

withMultiInputItemContainerMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes for the container of selected items. This adds to existing attributes.

config
    |> Select.withMultiInputItemContainerAttrs [ class "bg-white" ]

withMultiInputItemAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for an individual selected item.

config
    |> Select.withMultiInputItemAttrs [ class "bg-white" ]

withMultiInputItemMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to an individual selected item. This adds to existing attributes.

config
    |> Select.withMultiInputItemMoreAttrs [ class "bg-white" ]

Configure the input wapper

This is the element that wraps the selected item(s) and the input

withInputWrapperAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the input wrapper (element that wraps the input and the clear button). This overrides any attributes already set in a previous call.

config
    |> Select.withInputWrapperAttrs [ class "col-12" ]

withInputWrapperMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the input wrapper (element that wraps the input and the clear button). This adds to existing attributes.

config
    |> Select.withInputWrapperMoreAttrs [ class "col-12" ]

Configure the input

withInputAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the input. This overrides any attributes already set in a previous call.

config
    |> Select.withInputAttrs [ class "col-12" ]

withInputMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the input. This adds to existing attributes.

config
    |> Select.withInputMoreAttrs [ class "col-12" ]

withOnFocus : msg -> Config msg item -> Config msg item

Add a callback for when the input field receives focus.

config
    |> Select.withOnFocus OnFocus

withOnBlur : msg -> Config msg item -> Config msg item

Add a callback for when the input field loses focus.

config
    |> Select.withOnBlur OnBlur

withOnEsc : msg -> Config msg item -> Config msg item

Add a callback for when the Escape key is pressed.

config
    |> Select.withOnEsc OnEsc

Configure the clear button

withClear : Basics.Bool -> Config msg item -> Config msg item

Remove the clear button entirely

config
    |> Select.withClear False

withClearAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the clear button. This overrides any attributes already set in a previous call.

config
    |> Select.withClearAttrs [ class "clear" ]

withClearMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the clear button. This adds to existing attributes.

config
    |> Select.withClearMoreAttrs [ class "clear" ]

withClearSvgClass : String -> Config msg item -> Config msg item

Set classes for the clear SVG icon

config
    |> Select.withClearSvgClass "clear"

withClearHtml : Maybe (Html msg) -> Config msg item -> Config msg item

Use your own html for the clear icon

config
    |> Select.withClearHtml (Just (text "X"))

Configure the items

withItemAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the items. This overrides any attributes already set in a previous call.

config
    |> Select.withItemAttrs [ class "border-bottom" ]

withItemMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the items. This adds to existing attributes.

config
    |> Select.withItemMoreAttrs [ class "border-bottom" ]

withItemHtml : (item -> Html msg) -> Config msg item -> Config msg item

Custom item element HTML

config
    |> Select.withItemHtml (\i -> Html.li [] [ text i ])

When this is used the original toLabel function in the config is ignored.

withHighlightedItemAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the hightlighted item.

config
    |> Select.withHighlightedItemAttrs [ class "red" ]

withHighlightedItemMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the hightlighted item.

config
    |> Select.withHighlightedItemMoreAttrs [ class "red" ]

withItemSelectedAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the selected item in the menu.

config
    |> Select.withItemSelectedAttrs [ class "selected" ]

withItemSelectedMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the selected item in the menu.

config
    |> Select.withItemSelectedMoreAttrs [ class "selected" ]

Configure the menu

withMenuAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the menu. This overrides any attributes already set in a previous call.

config
    |> Select.withMenuAttrs [ class "bg-white" ]

withMenuMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the menu. This adds to existing attributes.

config
    |> Select.withMenuMoreAttrs [ class "bg-white" ]

Configure the not found message

withNotFound : String -> Config msg item -> Config msg item

Text that will appear when no matches are found.

config
    |> Select.withNotFound "No matches"

withNotFoundAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the not found message.

config
    |> Select.withNotFoundAttrs [ class "red" ]

withNotFoundMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the not found message. This adds to existing attributes.

config
    |> Select.withNotFoundMoreAttrs [ class "red" ]

withNotFoundShown : Basics.Bool -> Config msg item -> Config msg item

Hide menu when no matches found.

config
    |> Select.withNotFoundShown False

Configure the prompt

withPrompt : String -> Config msg item -> Config msg item

Add a prompt text to be displayed when no element is selected.

config
    |> Select.withPrompt "Select a movie"

withPromptAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Set attributes for the prompt text (When no item is selected)

config
    |> Select.withPromptAttrs [ class "prompt" ]

withPromptMoreAttrs : List (Html.Attribute msg) -> Config msg item -> Config msg item

Add attributes to the prompt text (When no item is selected) This adds to existing attributes.

config
    |> Select.withPromptMoreAttrs [ class "prompt" ]

State

init : String -> State

Create a new state. You must pass a unique identifier for each select component.

{
    ...
    selectState = Select.init "select1"
}

queryFromState : State -> Maybe String

Return the query string from the current state model

Select.queryFromState model.selectState

withQuery : Maybe String -> State -> State

Change the current query

Select.withQuery (Just "hello") selectModel

View

view : Config msg item -> State -> List item -> List item -> Html msg

Render the view

Select.view
    selectConfig
    model.selectState
    availableItems
    selectedItems

Update

update : Config msg item -> Msg item -> State -> ( State, Platform.Cmd.Cmd msg )

Update the component state

SelectMsg subMsg ->
    let
        ( updated, cmd ) =
            Select.update selectConfig subMsg model.selectState
    in
        ( { model | selectState = updated }, cmd )