PaackEng / elm-ui-dropdown / Dropdown

Elm UI Dropdown.

Component constructors

basic : { itemsFromModel : model -> List item, selectionFromModel : model -> Maybe item, dropdownMsg : Msg item -> msg, onSelectMsg : Maybe item -> msg, itemToPrompt : item -> Element msg, itemToElement : Basics.Bool -> Basics.Bool -> item -> Element msg } -> Config item msg model

Create a basic configuration. This takes:

filterable : { itemsFromModel : model -> List item, selectionFromModel : model -> Maybe item, dropdownMsg : Msg item -> msg, onSelectMsg : Maybe item -> msg, itemToPrompt : item -> Element msg, itemToElement : Basics.Bool -> Basics.Bool -> item -> Element msg, itemToText : item -> String } -> Config item msg model

Create a filterable configuration. This takes:

multi : { itemsFromModel : model -> List item, selectionFromModel : model -> List item, dropdownMsg : Msg item -> msg, onSelectMsg : List item -> msg, itemsToPrompt : List item -> Element msg, itemToElement : Basics.Bool -> Basics.Bool -> item -> Element msg } -> Config item msg model

Create a multiselect configuration. This takes:

autocompleteHelper : { itemsFromModel : model -> List item, selectionFromModel : model -> Maybe item, dropdownMsg : Msg item -> msg, onSelectMsg : Maybe item -> msg, onFilterChangeMsg : Maybe (String -> msg), itemToPrompt : item -> Element msg, itemToElement : Basics.Bool -> Basics.Bool -> item -> Element msg, itemToText : item -> String } -> Config item msg model

Create a configuration which can be used as an autocomplete. It emits a message on every filter change which can be handled in parent application to fetch predictions. This takes:

State


type Config item msg model

Opaque type that holds the current config

dropdownConfig =
    Dropdown.basic
        { allItems = always [ "apples", "bananas", "oranges" ]
        , selectedItem = .selectedFruit
        , dropdownMsg = DropdownMsg
        , onSelectMsg = FruitPicked
        , itemToPrompt = Element.text
        , itemToElement = \selected -> \highlighted -> Element.text
        }


type State item

Opaque type that holds the current state

type alias Model =
    { dropdownState : Dropdown.State
    }


type Msg item

Opaque type for the internal dropdown messages

init : String -> State item

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

{
    ...
    dropdownState = Dropdown.init "country-dropdown"
}

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

Update the component state

DropdownMsg subMsg ->
    let
        ( updated, cmd ) =
            Dropdown.update dropdownConfig subMsg model model.dropdownState model.items
    in
        ( { model | dropdownState = updated }, cmd )

view : Config item msg model -> model -> State item -> Element msg

Render the view

Dropdown.view dropdownConfig model model.dropdownState model.items

Effects


type Effect msg
    = Loopback msg
    | DomFocus (Result Browser.Dom.Error () -> msg) String

Allows tests with elm-program-test

mapEffect : (a -> b) -> Effect a -> Effect b

Same as Cmd.map, but for an Effect.

performEffect : Effect msg -> Platform.Cmd.Cmd msg

Resolves Effect as Elm's Cmds. If you plan to implement this yourself, it looks like this:

performEffect : Effect msg -> Cmd msg
performEffect effect =
    case effect of
        Loopback msg ->
            Task.perform identity <| Task.succeed msg

        DomFocus msg id ->
            Task.attempt msg (Dom.focus id)

updateWithoutPerform : Config item msg model -> Msg item -> model -> State item -> ( State item, List (Effect msg) )

Same as update but returning a list of Effect.

Options

onOutsideClick : State item -> (Msg item -> msg) -> Platform.Sub.Sub msg

Serves as a subscription to know when the user has clicked outside a certain dropdown

subscriptions : Model -> Sub Msg
subscriptions model =
    Dropdown.onOutsideClick model.dropdownState DropdownMsg

withContainerAttributes : List (Element.Attribute msg) -> Config item msg model -> Config item msg model

Sets the container visual attributes, default is empty

Dropdown.withContainerAttributes [ width (px 300) ] config

withEmptyListElement : Element msg -> Config item msg model -> Config item msg model

When the list is empty, show this element instead.

Most useful in filterable, it shows up when nothing matches the filter value.

withFilterPlaceholder : String -> Config item msg model -> Config item msg model

Sets the placeholder of the Filterable dropdown, default is "Filter values"

Dropdown.withFilterPlaceholder "Type here..." config

withListAttributes : List (Element.Attribute msg) -> Config item msg model -> Config item msg model

Sets the item list visual attributes, default is empty

Dropdown.withListAttributes [ Border.width 1, Border.rounded ] config

withOpenCloseButtons : { openButton : Element msg, closeButton : Element msg } -> Config item msg model -> Config item msg model

Sets the open and close buttons' visual attributes, default is empty

Dropdown.withOpenCloseButtons { openButton = text "+", closeButton = "-" } config

withPromptElement : Element msg -> Config item msg model -> Config item msg model

Sets the content of the Select, default is "-- Select --"

Dropdown.withPromptElement (el [ Font.color (rgb255 123 123 123) ] <| text "Pick one") config

withSearchAttributes : List (Element.Attribute msg) -> Config item msg model -> Config item msg model

Sets the search visual attributes, default is empty

Dropdown.withSearchAttributes [ Border.width 0, padding 0 ] config

withSelectAttributes : List (Element.Attribute msg) -> Config item msg model -> Config item msg model

Sets the select visual attributes, default is empty

Dropdown.withSelectAttributes [ Border.width 1, Border.rounded 5, paddingXY 16 8 ] config