AvardaUi.SuggestionInput

This module provides a component that allows you to get autocomplete suggestions. These can be either hardcoded or you can use remote suggestions obtained from API call. It uses the builder pattern:

Start with new to create a base input.
Chain configuration functions like withPlaceholder or withIsRequired.
Finish with view to render it.

Creating a SuggestionInput

type alias Model a =

Model a

Model type for the SuggestionInput component. Use this in your own model.

type alias ContactInfoModel =
    { addressSuggestionInputModel : AvardaUi.SuggestionInput.Model Address }

init : String -> Model a

Initialize the SuggestionInput model.

init : ContactInfoModel
init =
    { addressSuggestionInputModel = AvardaUi.SuggestionInput.init "address" }

setSuggestions : List a -> Model a -> Model a

Used after init to use hardcoded list of suggestions.

reinit : Model a -> Model a

In some cases it's nice to have the option to re-init the component with no need to pass id again.

type alias Msg a =

Msg a

Msg type for the SuggestionInput component. Use this for the wrap msg in your own Msg type.

type ContactInfoMsg
    = HandleAddressSuggestionInput (AvardaUi.SuggestionInput.Msg Address)
    | NoUpdate

update : (Msg a -> msg) -> Msg a -> Model a -> ( Model a, Cmd msg )

update : Model -> Msg -> ( Model, Cmd Msg )
update model msg =
    case msg of
        HandleAddressSuggestionsInput suggestionInputMsg ->
            let
                ( HandleAddressSuggestionInput, suggestionInputCmd ) =
                    SuggestionInput.update
                        HandleAddressSuggestionsInput
                        suggestionInputMsg
                        model.addressSuggestionInputModel
            in
            ( { model | addressSuggestionInputModel = HandleAddressSuggestionInput }, suggestionInputCmd )

new :

{ label : String

, suggestionInputModel : Model a

, suggestionToInputValue : a -> String

}

-> SuggestionInput a msg

Create a new SuggestionInput component.

AvardaUi.SuggestionInput.new
    { label = "Address"
    , suggestionInputModel = addressSuggestionInputModel
    , suggestionToInputValue = .addressLine1
    }

view : (Msg a -> msg) -> SuggestionInput a msg -> Html msg

Render the Select as HTML.

Always call this after you've built up the input with new and chained settings.

AvardaUi.SuggestionInput.new "address"
    |> AvardaUi.SuggestionInput.withIsRequired True
    |> AvardaUi.SuggestionInput.view

Setting suggestion list

To use it with the hardcoded list of suggestions, just setSuggestions after init.

SuggestionInput.init "address"
    |> SuggestionInput.setSuggestions suggestionList

If you wish to use it with remote suggestions, add a remoteSuggestions update option in your updateWith function.

SuggestionInput.updateWith
    [ SuggestionInput.remoteSuggestions { requestCmd = fetchSuggestions, requestMinInputLength = 3 } ]

Setting input value

setInputValue : String -> Model a -> Model a

Set the input value.

Getting selected suggestion

getSelectedSuggestion : Model a -> Maybe a

Get the currently selected suggestion. If none is selected, returns Nothing. Note that if you select a suggestion and then write anything to the input, the suggestion is no longer selected in the model

Update with extra options

You can pass extra options / callbacks to this component using updateWith

updateWith :

List (UpdateOption a msg)

-> (Msg a -> msg)

-> Msg a

-> Model a

-> ( Model a, Cmd msg )

update : Model -> Msg -> ( Model, Cmd Msg )
update model msg =
    case msg of
        HandleAddressSuggestionsInput suggestionInputMsg ->
            let
                ( HandleAddressSuggestionInput, suggestionInputCmd ) =
                    SuggestionInput.updateWith
                        [ SuggestionInput.onInput InsertedAddress
                        , SuggestionInput.onSelect ClickedAddressSuggestion
                        ]
                        HandleAddressSuggestionsInput
                        suggestionInputMsg
                        model.addressSuggestionInputModel
            in
            ( { model | addressSuggestionInputModel = HandleAddressSuggestionInput }, suggestionInputCmd )

onSelect : (a -> msg) -> UpdateOption a msg

Used for triggering a message when suggestion is selected.

onInput : (String -> msg) -> UpdateOption a msg

Used for triggering a message when the input is typed into.

remoteSuggestions : RemoteSuggestionsPayload a msg -> UpdateOption a msg

Used in updateWith in order to use suggestions obtain from an API call instead of hardcoded ones set with setSuggestions.

The RemoteSuggestionsPayload looks like this:

type alias RemoteSuggestionsPayload a msg =
    { requestCmd : String -> (RemoteData.WebData (List a) -> msg) -> Cmd msg
    , requestMinInputLength : Int
    }

where String is the request's query.

Example of the requestCmd:

getAddressSuggestions : String -> (RemoteData.WebData (List Address) -> msg) -> Cmd msg
getAddressSuggestions query msg =
    { method = "GET"
    , headers = []
    , url = "https://api.example.com/suggestions?query=" ++ query
    , body = Http.emptyBody
    , expect = Http.expectJson (RemoteData.fromResult >> msg) addressSuggestionDecoder
    , timeout = Nothing
    , tracker = Nothing
    }
        |> Http.request

scrollSuggestionIntoView : ScrollSuggestionIntoViewCmd msg -> UpdateOption a msg

Used to fix issue with scrolling option into view when used in ShadowDOM. elm/browser cannot find the element ID when this component is used by an app which uses ShadowDOM

type alias ScrollOptionIntoViewCmd msg =
    String -> Cmd msg

Configuration

withBorderRadius : Float -> SuggestionInput a msg -> SuggestionInput a msg

Adjust the border radius of the input box.

withHint : String -> SuggestionInput a msg -> SuggestionInput a msg

Add a hint text below the input.

withPlaceholder : String -> SuggestionInput a msg -> SuggestionInput a msg

Add a placeholder to the input.

withIsDisabled : Bool -> SuggestionInput a msg -> SuggestionInput a msg

Disable the input. Visually dims and prevents user actions.

withIsRequired : Bool -> SuggestionInput a msg -> SuggestionInput a msg

Mark the input as required. This adds a * to the label and sets required=true.

withMaybeError : Maybe String -> SuggestionInput a msg -> SuggestionInput a msg

Show an error message and mark the input invalid. Replaces any active hint text.

withMenuMaxHeight : Int -> SuggestionInput a msg -> SuggestionInput a msg

Set a maximum height for the dropdown menu.

withAriaLabel : String -> SuggestionInput a msg -> SuggestionInput a msg

Set a custom ARIA label.

withAutocomplete : String -> SuggestionInput a msg -> SuggestionInput a msg

Enable autocomplete with a given string like "address1". It is set to "off" by default.

withCustomSuggestionViewFn : (a -> Html msg) -> SuggestionInput a msg -> SuggestionInput a msg

Provide a custom view function for rendering suggestions.

withLeftChild : Html msg -> SuggestionInput a msg -> SuggestionInput a msg

Add a left-side child element.

withRightChild : Html msg -> SuggestionInput a msg -> SuggestionInput a msg

Add a right-side child element.

withSelectedSuggestionAdditionalStyles : List Style -> SuggestionInput a msg -> SuggestionInput a msg

Provide additional styles for the selected suggestion.

withTopPx : Float -> SuggestionInput a msg -> SuggestionInput a msg

Adjust the gap between the Select and the dropdown menu.

avarda-ab/avarda-ui/2.0.0