Field

Renders a form field including input, label, errors, and description.

Read more Read less

A Phoenix.HTML.FormField may be passed as argument, which is used to retrieve the input name, id, and values. Otherwise all attributes may be passed explicitly.

Usage

Types

In addition to all HTML input types, the following type values are also supported:

  • "select"
  • "checkbox-group"
  • "radio-group"
  • "switch"

Class and Global Attribute

Note that the class attribute is applied to the outer container, while the rest global attribute is applied to the <input> element.

Gettext

To translate field errors using Gettext, set the gettext_module option when building the component:

build_field(gettext_module: MyApp.Gettext)

Label positioning

The component does not provide an attribute to modify label positioning directly. Instead, label positioning should be handled with CSS. If your application requires different label positions, such as horizontal and vertical layouts, it is recommended to add a modifier class to the form.

For example, the default style could position labels above inputs. To place labels to the left of the inputs in a horizontal form layout, you can add an is-horizontal class to the form:

<.form class="is-horizontal">
<!-- inputs -->

</.form>

Then, in your CSS, apply the necessary styles to the .field class within forms having the is-horizontal class:

form.is-horizontal .field {
  // styles to position label left of the input
}

The component has a hide_label attribute to visually hide labels while still making them accessible to screen readers. If all labels within a form need to be visually hidden, it may be more convenient to define a .has-visually-hidden-labels modifier class for the <form>.

<.form class="has-visually-hidden-labels">
<!-- inputs -->

</.form>

Ensure to take checkbox and radio labels into consideration when writing the CSS styles.

Examples

<.field field={@form[:name]} />
<.field field={@form[:email]} type="email" />

Radio group and checkbox group

The radio-group and checkbox-group types allow you to easily render groups of radio buttons or checkboxes with a single component invocation. The options attribute is required for these types and has the same format as the options for the select type, except that options may not be nested.

<.field
  field={@form[:email]}
  type="checkbox-group"
  label="Cuisine"
  options={[
    {"Mexican", "mexican"},
    {"Japanese", "japanese"},
    {"Libanese", "libanese"}
  ]}
/>

Note that the checkbox-group type renders an additional hidden input with an empty value before the checkboxes. This ensures that a value exists in case all checkboxes are unchecked. Consequently, the resulting list value includes an extra empty string. While Ecto.Changeset.cast/3 filters out empty strings in array fields by default, you may need to handle the additional empty string manual in other contexts.

Radio group
Checkbox group
Attribute Type Documentation Default Value
checked :boolean The checked attribute for checkboxes.
checked_value :string The value that is sent when the checkbox is checked. "true"
class :any Any additional classes to be added. Variations of the component should be expressed via modifier attributes, and it is preferable to use styles on the parent container to arrange components on the page, but if you have to, you can use this attribute to pass additional utility classes to the component. The value can be a string or a list of strings. []
errors :list
field %FormField{} A form field struct, for example: @form[:name]
gettext :atom The Gettext module to use for translating error messages. This option can also be set globally, see above.
hide_label :boolean Adds an "is-visually-hidden" class to the `<label>`. This option does not apply to checkbox and radio inputs. false
id :any
label :string Required for all types except `"hidden"`.
multiple :boolean Sets the `multiple` attribute on a select element to allow selecting multiple options. false
name :any
off_text :string The state text for a switch when off. "Off"
on_text :string The state text for a switch when on. "On"
options :list A list of options. This attribute is supported for the following types: - `"select"` - `"radio-group"` - `"checkbox-group"` - other text types, date and time types, and the `"range"` type If this attribute is set for types other than select, radio, and checkbox, a [datalist](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) is rendered for the input. See `Phoenix.HTML.Form.options_for_select/2` for the format. Note that only the select supports nested options.
prompt :string An optional prompt for select elements.
required_text :atom The presentational text or symbol to be added to labels of required inputs. This option can also be set globally: config :doggo, required_text: "required"
required_title :atom The `title` attribute for the `required_text`. This option can also be set globally: config :doggo, required_title: "required"
rest :global
type :string "text"
validations :list A list of HTML input validation attributes (`required`, `minlength`, `maxlength`, `min`, `max`, `pattern`). The attributes are derived automatically from the form.
value :any
addon_left :slot Can be used to render an icon left in the input. Only supported for single-line inputs.
addon_right :slot Can be used to render an icon left in the input. Only supported for single-line inputs.
description :slot A field description to render underneath the input.