PaackEng / paack-ui / UI.Dropdown

Accessible and uniform-styled implementation of a dropdown menu.

Dropdown.basic
    { dropdownMsg = ForDropdownMsg
    , onSelectMsg = GotSelectItemMsg
    , state = model.dropdownState
    }
    |> Dropdown.withPlaceholder "Choose a book"
    |> Dropdown.withItems model.books
    |> Dropdown.withSelected model.selectedBook
    |> Dropdown.withItemToText Books.getTitle
    |> Dropdown.renderElement renderConfig

Dropdown


type Dropdown item msg

The Dropdown item msg type is used for describing the component for later rendering.


type alias BasicConfig item msg =
{ dropdownMsg : Msg item -> msg
, onSelectMsg : Maybe item -> msg
, state : State item 
}

BasicConfig assembles the required configuration for having a simple dropdown.

{ dropdownMsg = ForDropdownMsg
, onSelectMsg = GotSelectItemMsg
, state = model.dropdownState
}

basic : BasicConfig item msg -> Dropdown item msg

Constructs a basic dropdown. Also defines the handling function for messages, and the current dropdown's state.

Dropdown.basic
    { dropdownMsg = ForDropdownMsg
    , onSelectMsg = GotSelectItemMsg
    , state = model.dropdownState
    }

filterable : BasicConfig item msg -> Dropdown item msg

Constructs a filterable dropdown. Also defines the handling function for messages, and the current dropdown's state.

Dropdown.filterable
    { dropdownMsg = ForDropdownMsg
    , onSelectMsg = GotSelectItemMsg
    , state = model.dropdownState
    }

State


type State item

Keep this one in your Model, it holds the dropdown's current state.


type Msg item

Opaque type for the internal dropdown messages

init : String -> State item

The correct way of instantiating a Dropdown.State.

{ -- ...
, state = Dropdown.init "dropdown-id"
-- ...
}

update : UI.RenderConfig.RenderConfig -> Msg item -> Dropdown item msg -> ( State item, UI.Effects.Effects msg )

Given a message, apply an update to the Dropdown.State. Do not ignore the returned Effect, it may include remote select's messages.

( newModel, newCmd ) =
    Dropdown.update renderConfig subMsg dropdown

Options

withPlaceholder : String -> Dropdown item msg -> Dropdown item msg

Changes the component's placeholder text.

Dropdown.withPlaceholder "Choose a book"
    someDropdown

withFilterPlaceholder : String -> Dropdown item msg -> Dropdown item msg

Changes the filterable component's placeholder text.

Dropdown.withPlaceholder "Choose a book"
    someDropdown

withItems : List item -> Dropdown item msg -> Dropdown item msg

Changes the component's list of elements.

Dropdown.withItems
    [ { id = 0, name = "Entry A" }
    , { id = 1, name = "Entry B" }
    ]
    someDropdown

withSelected : Maybe item -> Dropdown item msg -> Dropdown item msg

Marks the element as selected.

Dropdown.withSelected (List.head model.entries)
    someDropdown

withItemToText : (item -> String) -> Dropdown item msg -> Dropdown item msg

Changes the way elements are formatted.

Dropdown.withItemToText .name
    someDropdown

withItemToPrompt : (item -> String) -> Dropdown item msg -> Dropdown item msg

Changes the way prompt is formatted.

Dropdown.withItemToPrompt (.name >> String.toUpper)
    someDropdown

withMaximumListHeight : Basics.Int -> Dropdown item msg -> Dropdown item msg

Changes the maximum height of the dropdown list.

Dropdown.withMaximumListHeight 200
    someDropdown

withListWidth : Basics.Int -> Dropdown item msg -> Dropdown item msg

Set the width of list dropdown, in case it needs to have a different width then the prompt.

Dropdown.withListWidth 200
    someDropdown

withListAlignedRight : Basics.Bool -> Dropdown item msg -> Dropdown item msg

Sets the alignment of dropdown list in case its width differs from prompt.

Dropdown.withListAlignedRight True
    someDropdown

Rendering

renderElement : UI.RenderConfig.RenderConfig -> Dropdown item msg -> Element msg

End of the builder's life. The result of this function is a ready-to-insert Elm UI's Element.