This is an alternative site for discovering Elm packages. You may be looking for the official Elm package site instead.
We were not able to find the expected elm-package.json file at this tag.
Tag 1.2.1
Committed At 2019-06-04 01:58:34 UTC



    Form Validator Icon

    Form Validator

    Circle CI Status

    Provides a customizable form validation component for use within your views.

    Table of Contents


    • Supports multi-form management.
    • Supports multiple fields within a form.
    • Supports validation of a single field or entire form.
    • Supports field access and update management.
    • Supports single or multiple field values.
    • Supports single or multiple field errors.
    • Supports many types of validations. Examples:
      • Blank
      • Empty
      • Integer
      • Float
      • Included
      • Excluded
      • LessThan
      • LessThanEqualTo
      • GreaterThan
      • GreaterThanEqualTo
      • Between
      • LengthLessThan
      • LengthLessThanEqualTo
      • LengthGreaterThan
      • LengthGreaterThanEqualTo
      • LengthBetween
      • Email
    • Supports custom validators and UI styling.
    • Provides view helpers for rendering a form or field with or without errors.


    The following demonstrates an example form (which will be styled differently for your implementation) before and after validation has occured.

    Blank Form

    Invalid Form



    To setup and install, run:

    elm package install bkuhlmann/form-validator

    You can import FormValidator as follows:

    import FormValidator as Validator


    This package supports a basic out-of-the-box experience in addition to full customization. The following provides a general overview before digging into the specifics.


    A basic model-view-update implementation might look like this:

    module Pages.Example exposing (..)
    import FormValidator as Validator
    -- TYPES
    type FieldKey
      = Name
      | Email
    type Message
      = FieldInput FieldKey String
      | FieldBlur FieldKey
      | Save
    -- MODELS
    type alias Model =
        form: Validator FieldKey
    -- RECORDS
    initialModel : Model
    initialModel =
        form = [
          Validator.init Name [Validator.isBlank],
          Validator.init Email [Validator.isEmail]
    -- VIEWS
    view : Model -> Html Message
    view model =
      Validator.viewField Name model.form ["example-field-class"] [
        label [for "name"] [text "Name"],
        input [
          class "example-input-class",
          name "name",
          type_ "text",
          value <| Validator.fieldValue Name model.form,
          onInput <| FieldInput Name,
          onBlur <| FieldBlur Name
        ] []
    -- UPDATE
    update : Message -> Model -> (Model, Cmd Message)
    update message model =
      case message of
        FieldInput key value ->
          ({model | form = Validator.updateValue key value model.form}, Cmd.none)
        FieldBlur key ->
          ({model | form = Validator.validateField key model.form}, Cmd.none)
        Save ->
            validatedModel = {model | form = Validator.validateForm model.form}
            if Validator.isFormInvalid validatedModel.form then
              (validatedModel, Cmd.none)
              (validatedModel, saveCommand validatedModel)

    Field Keys

    The Form Validator design encourages one to use a union type for field keys so the compiler does most of the work for you should a field name be renamed, removed, etc. That said, you can use any type for the key but would recommend sticking with a union type if possible.

    In the above Overview, the following field key type was used:

    type FieldKey
      = Name
      | Email

    This is handy because you can add as many keys for as many fields of your form as necessary. You can also use multiple union types for different forms on your page. Example:

    type ContactKey
      = Name
      | Email
      | Bio
    type AddressKey
      = Line1
      | Line2
      | Country
      | State
      | Zip


    The Form Validator is flexible in that it can be used to represent a single form on a page:

    type alias Model =
        form: Validator FieldKey

    ...or multiple forms, depending on your need:

    type alias Model =
        contactForm: Validator ContactKey,
        addressForm: Validator AddressKey


    Using the model examples above, you can define as many validators as necessary for fields in your form(s). Example:

    initialModel : Model
    initialModel =
        contactForm = [
          Validator.init Name [
            Validator.isLengthGreaterThanEqualTo 5
          Validator.init Email [
        addressForm: [
          Validator.init Line2 []

    The validator is initialized with a key and a list of validators. The list can be empty or contain several validators per field. An empty validator list allows you to define a form field that has no need of validation while also being able to manage that form field like any other form field. A form field with multiple validators can result in a list of multiple errors (if any or all of them turn out to be invalid).

    Each initialized validator is a partial function which means you can define the validator with the necessary requirements (if any). When the form or field is validated later, the value (or values) of each field will be supplied to each function at runtime to compute if the field is valid or invalid.


    The Form Validator comes with a few functions for rendering results in your view. One of which is the viewField function which renders a div around your input field. For example, let's look at the following code:

    Validator.viewField Name model.form ["example-field-class"] [
      label [for "name"] [text "Name"],
      input [
        class "example-input-class",
        name "name",
        type_ "text",
        value <| Validator.fieldValue Name model.form,
        onInput <| FieldInput Name,
        onBlur <| FieldBlur Name
      ] []

    The above will generate the following HTML output when a field fails validation:

    <div class="form_validator-field_error">
      <ul class="form_validator-errors">
        <li class="form_validator-error">...</li>

    This allows you to customize the look and feel of the following classes within the DOM:

    • form_validator-field_error: The wrapper div for the invalid form field.
    • form_validator-errors: The unordered list of field errors.
    • form_validator-error: The individual field error list item.


    When updating your form, this'll usually occur via one following functions:

    • updateValue: Allows you to update a field's value for a given key.
    • updateValues: Similar to the above function but allows for multiple field values to be updated.
    • updateAndValidateValue: Combines two steps into one, allowing you to update and validate a field at once.
    • updateAndValidateValues: Similar to the above but for multiple field values.
    • validateForm: Allows you to update and validate an entire form. Handy when preventing a form being saved due to detected errors.


    By default, the FormValidator module is provided to you as a single module you can import and use within your application immediately. It's a wrapper module around the other modules found within the FormValidator namespace/directory. This was done in order to give you a single module to import and get started quickly.

    Should you not want the default behavior provided by the FormValidator module, you can ignore importing that module and import the individual modules as you see fit for your customization needs. Here is a breakdown of the other modules available to you:

    • FormValidator/Models: These are the models use to represent the form, field, values, and errors of a form.
    • FormValidator/Patterns: These are the regular expression patterns used for some of the validators. These are available to you should you need them for different purposes.
    • FormValidator/Validator: Contains all functions related to updating and validating forms and fields.
    • FormValidator/Validators: Provides pre-defined validators for various checks. These might be all you need or your might want to craft your own validators as business requirements dictate.
    • FormValidator/Views: These are functions which help you render form and form field errors.

    By being able to import any module, you can better mix and match functionality for your specific needs without having to compile code you don't need.


    To test, run:

    yarn test


    Read Semantic Versioning for details. Briefly, it means:

    • Major (X.y.z) - Incremented for any backwards incompatible public API changes.
    • Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
    • Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

    Code of Conduct

    Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.


    Read CONTRIBUTING for details.


    Copyright 2018 Alchemists. Read LICENSE for details.


    Read CHANGES for details. Built with Gemsmith.


    Developed by Brooke Kuhlmann at Alchemists.