An opaque type representing a form with multiple inputs.

A Form contains form-level attributes and a collection of inputs that will be rendered together.

Represents an input field within a form.

Each input has a unique key that identifies it in the form's value dictionary, and configuration for how the input should behave and appear.

Note: You should create FormInput values using the input function rather than constructing this record directly. The input function provides a clean, type-safe way to create form inputs.

Create a new form with form-level attributes and inputs.

import Html.Attributes as Attr


myForm : Form Msg
myForm =
    new [ Attr.class "my-form" ]
        [ input "email" "Email Address"
            |> withType "email"
            |> withRequired True
        , input "name" "Full Name"
            |> withRequired True
        ]

Create a new form input with a key and label.

The key is used to identify the input's value in the form state dictionary.

input "username" "Username"


input "bio" "Biography"
    |> withType "textarea"

Mark an input as required or optional.

input "email" "Email"
    |> withRequired True

Set the input type (e.g., "text", "email", "password", "number").

input "password" "Password"
    |> withType "password"
    |> withRequired True


input "age" "Age"
    |> withType "number"

Add placeholder text to an input.

input "search" "Search"
    |> withPlaceholder "Type to search..."


input "email" "Email Address"
    |> withType "email"
    |> withPlaceholder "[email protected]"

Add a transformer function that processes the input value before it's stored.

Transformers are useful for formatting input, such as removing whitespace or converting to a specific case.

input "username" "Username"
    |> withTransformer String.trim


input "code" "Postal Code"
    |> withTransformer String.toUpper

Add a validator function that returns additional HTML attributes on validation failure.

Validators can return attributes like CSS classes or ARIA attributes to provide visual feedback when validation fails.

import Html.Attributes as Attr


emailValidator : String -> Result (List (Html.Attribute msg)) ()
emailValidator value =
    if String.contains "@" value then
        Ok ()
    else
        Err [ Attr.class "error", Attr.attribute "aria-invalid" "true" ]


input "email" "Email"
    |> withType "email"
    |> withValidator emailValidator

Add custom HTML attributes to an input.

import Html.Attributes as Attr


input "name" "Name"
    |> withAttributes
        [ Attr.class "form-control"
        , Attr.placeholder "Enter your name"
        ]

Render the form to HTML.

Takes the current form values as a dictionary, a message constructor for handling value changes, a message for form submission, and the form configuration.

import Dict exposing (Dict)


type Msg
    = FormChanged (Dict String String)
    | FormSubmitted


view : Dict String String -> Html Msg
view formValues =
    myForm
        |> build formValues FormChanged FormSubmitted