View Source BitstylesPhoenix.Component.Form (bitstyles_phoenix v2.5.0)

Components for rendering input elements.

Use ui_input, ui_select, ui_textarea to render the respective inputs together with a label and errors. Alternatively, this module also provides ui_raw_input and ui_raw_label functions that can be used to render only an input or only a label.

Common attributes

All ui_* components in this module accept the following attributes.

  • form (required) - The form to render the input form.
  • field (required) - The name of the field for the input.
  • label - The text to be used as label. Defaults to a title-cased name of the field.
  • label_opts - The options passed to the label element generated with BitstylesPhoenix.Component.Form.ui_raw_label/1.

For details on how to render a form, see:

Summary

Functions

Renders various types of <input> element, with the associated <label>s, and any errors for that field.

Renders an input, select, or textarea. Direct usage is discouraged. Use ui_input instead that comes with a label and errors.

Renders a label. Direct usage is discouraged in favor of ui_input that comes with a label.

Renders a <select> element, with a <label> and any errors for that field.

Renders <textarea> elements, with the associated <label>s, and any errors for that field.

Component for rendering custom inputs together with a label and errors.

Component for rendering custom wrapped inputs in a label and with errors.

Functions

Renders various types of <input> element, with the associated <label>s, and any errors for that field.

Attributes

  • type - The type of the input. Defaults to type="text".
  • hidden_label - Only show the label for screen readers if set to true.
  • All options from above (see top level module doc).
  • All other attributes will be passed onto the input element. Defaults to maxlength="255" for email, text and password type. Set maxlength to false to prevent setting maxlength.

Types

This function accepts all HTML input types, considering that:

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input for more information. Unsupported types, such as hidden and radio, are best written directly in your templates.

See the bitstyles form docs for examples of inputs, selects, textareas, labels etc. in use. See the bitstyles form docs for examples of form layouts.

Text field with label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:name} />
...> """
"""
<label for="user_name">
  Name
</label>
<input id="user_name" name="user[name]" type="text" maxlength="255"/>
"""

Text field with custom id with label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} id={"the_name"} field={:name} />
...> """
"""
<label for="the_name">
  Name
</label>
<input id="the_name" name="user[name]" type="text" maxlength="255"/>
"""

Text required field with label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:name} required/>
...> """
"""
<label for="user_name">
  Name
  <span aria-hidden="true" class="u-fg-warning u-margin-xxs-left">
    *
  </span>
</label>
<input id="user_name" name="user[name]" type="text" maxlength="255" required="required"/>
"""

Text field with error

iex> assigns=%{form: form_with_errors()}
...> render ~H"""
...> <.ui_input form={@form} field={:name} />
...> """
"""
<label for="user_name">
  Name
</label>
<input id="user_name" name="user[name]" type="text" maxlength="255"/>
<span class="u-fg-warning" phx-feedback-for="user[name]">
  is too short
</span>
"""

Text field with multiple errors

iex> assigns=%{form: form_with_errors()}
...> render ~H"""
...> <.ui_input form={@form} field={:email} />
...> """
"""
<label for="user_email">
  Email
</label>
<input id="user_email" name="user[email]" type="text" maxlength="255"/>
<ul class="u-padding-l3-left">
  <li>
    <span class="u-fg-warning" phx-feedback-for="user[email]">
      is invalid
    </span>
  </li>
  <li>
    <span class="u-fg-warning" phx-feedback-for="user[email]">
      must end with @bitcrowd.net
    </span>
  </li>
</ul>
"""

Text field with hidden label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:name} hidden_label={true} />
...> """
"""
<label for="user_name" class="u-sr-only">
  Name
</label>
<input id="user_name" name="user[name]" type="text" maxlength="255"/>
"""

Text field with label (without maxlength)

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:name} maxlength={false}/>
...> """
"""
<label for="user_name">
  Name
</label>
<input id="user_name" name="user[name]" type="text"/>
"""

Text field with options

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input
...>   form={@form}
...>   field={:totp}
...>   label="Authentication code"
...>   label_opts={[class: "extra"]}
...>   placeholder="6-digit code"
...>   required={true}
...>   value=""
...>   inputmode="numeric"
...>   pattern="[0-9]*"
...>   autocomplete="one-time-code"
...>   maxlength={6} />
...> """
"""
<label for="user_totp" class="extra">
  Authentication code
  <span aria-hidden="true" class="u-fg-warning u-margin-xxs-left">
    *
  </span>
</label>
<input id="user_totp" name="user[totp]" type="text" autocomplete="one-time-code" inputmode="numeric" maxlength="6" pattern="[0-9]*" placeholder="6-digit code" required="required" value=""/>
"""

Email field with label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:email} type={:email} />
...> """
"""
<label for="user_email">
  Email
</label>
<input id="user_email" name="user[email]" type="email" maxlength="255"/>
"""

Search field with placeholder

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input
...>    form={@form}
...>    field={:email_or_name}
...>    type={:search}
...>    placeholder="Search by email or name"
...>    autofocus={true} />
...> """
"""
<label for="user_email_or_name">
  Email or name
</label>
<input id="user_email_or_name" name="user[email_or_name]" type="search" autofocus="autofocus" placeholder="Search by email or name"/>
"""

File field for pdfs

iex> assigns=%{form: form()}
...> render ~H"""
...> <Phoenix.Component.form :let={form} for={@form} multipart>
...>   <.ui_input form={form} field={:file} type={:file} accept="application/pdf" />
...> </Phoenix.Component.form>
...> """
"""
<form enctype="multipart/form-data">
  <label for="user_file">
    File
  </label>
  <input id="user_file" name="user[file]" type="file" accept="application/pdf"/>
</form>
"""

Checkbox

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:accept} type={:checkbox} />
...> """
"""
<label for="user_accept">
  <input name="user[accept]" type="hidden" value="false"/>
  <input id="user_accept" name="user[accept]" type="checkbox" value="true"/>
  Accept
</label>
"""

Checkbox required

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:accept} type={:checkbox} required/>
...> """
"""
<label for="user_accept">
  <input name="user[accept]" type="hidden" value="false"/>
  <input id="user_accept" name="user[accept]" type="checkbox" value="true" required="required"/>
  Accept
  <span aria-hidden="true" class="u-fg-warning u-margin-xxs-left">
    *
  </span>
</label>
"""

Checkbox with label class

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_input form={@form} field={:accept} type={:checkbox} label_opts={[class: "extra"]}/>
...> """
"""
<label for="user_accept" class="extra">
  <input name="user[accept]" type="hidden" value="false"/>
  <input id="user_accept" name="user[accept]" type="checkbox" value="true"/>
  Accept
</label>
"""

Renders an input, select, or textarea. Direct usage is discouraged. Use ui_input instead that comes with a label and errors.

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.

Types

This function accepts all HTML input types, considering that:

  • You may also set type="select" to render a <select> tag
  • type="checkbox" is used exclusively to render boolean values
  • For live file uploads, see Phoenix.Component.live_file_input/1

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input for more information. Unsupported types, such as hidden and radio, are best written directly in your templates.

Attributes

  • field - a Phoenix.HTML.FormField struct retrieved from the form, for example: @form[:email]
  • type - string or atom, defaults to :text
  • id - string, required if field not passed
  • name - string, required if field not passed
  • value - any, required if field not passed
  • checked - boolean, required if type="checkbox"
  • options - list, required if type="select"
  • multiple - boolean, used if type="select"
  • prompt - string, used if type="select"
  • any other attributes, they will be passed to the input element

Input (from field)

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_raw_input field={@form[:name]} />
...> """
"""
<input id="user_name" name="user[name]" type="text"/>
"""

Input (email)

iex> assigns=%{}
...> render ~H"""
...> <.ui_raw_input id="the_email" name="user[email]" type={:email} value="" class="foo bar"/>
...> """
"""
<input id="the_email" name="user[email]" type="email" class="foo bar" value=""/>
"""

Input (checkbox)

iex> assigns=%{}
...> render ~H"""
...> <.ui_raw_input id="the_newsletter" name="user[wants_newsletter]" type={:checkbox} checked={false} data-theme="pink"/>
...> """
"""
<input name="user[wants_newsletter]" type="hidden" value="false"/>
<input id="the_newsletter" name="user[wants_newsletter]" type="checkbox" value="true" data-theme="pink"/>
"""

Input (select)

iex> assigns=%{}
...> render ~H"""
...> <.ui_raw_input id="the_day" name="user[dob_day]" type={:select} options={[{"Monday", 1},{"Tuesday", 2}]} value={2} prompt={"On which day were you born?"} data-foo=""/>
...> """
"""
<select id="the_day" name="user[dob_day]" data-foo="">
  <option value="">
    On which day were you born?
  </option>
  <option value="1">
    Monday
  </option>
  <option selected="selected" value="2">
    Tuesday
  </option>
</select>
"""

Renders a label. Direct usage is discouraged in favor of ui_input that comes with a label.

Attributes

  • for - id of the input the label belongs to.

Label

iex> assigns=%{}
...> render ~H"""
...> <.ui_raw_label for="user_address_city" class="foo bar">
...>   City
...> </.ui_raw_label>
...> """
"""
<label for="user_address_city" class="foo bar">
  City
</label>
"""

Label (no for)

iex> assigns=%{}
...> render ~H"""
...> <.ui_raw_label class="foo bar">
...>   Note
...>   <input type="text" name="note"/>
...> </.ui_raw_label>
...> """
"""
<label class="foo bar">
  Note
  <input type="text" name="note"/>
</label>
"""

Renders a <select> element, with a <label> and any errors for that field.

Attributes

  • hidden_label - Only show the label for screen readers if set to true.
  • options - The options passed to Phoenix.HTML.Form.options_for_select/2.
  • prompt - Will be rendered as the first option with an empty value.
  • All options from above (see top level module doc).
  • All other attributes will be passed onto the select element.

See the bitstyles select docs for examples of selects and labels in use.

Select box

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_select form={@form} field={:week} options={1..2} />
...> """
"""
<label for="user_week">
  Week
</label>
<select id="user_week" name="user[week]">
  <option value="1">
    1
  </option>
  <option value="2">
    2
  </option>
</select>
"""

Select box required

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_select form={@form} field={:week} options={1..2} required />
...> """
"""
<label for="user_week">
  Week
  <span aria-hidden="true" class="u-fg-warning u-margin-xxs-left">
    *
  </span>
</label>
<select id="user_week" name="user[week]" required="required">
  <option value="1">
    1
  </option>
  <option value="2">
    2
  </option>
</select>
"""

Select box without label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_select form={@form} field={:week} options={1..2} hidden_label/>
...> """
"""
<label for="user_week" class="u-sr-only">
  Week
</label>
<select id="user_week" name="user[week]">
  <option value="1">
    1
  </option>
  <option value="2">
    2
  </option>
</select>
"""

Select box with options

iex> assigns=%{form: form(), options: [{"Ducks", "ducks"}, {"Cats", "cats"}]}
...> render ~H"""
...> <.ui_select form={@form} field={:preference} options={@options} label="What do you like best?" label_opts={[class: "extra"]}/>
...> """
"""
<label for="user_preference" class="extra">
  What do you like best?
</label>
<select id="user_preference" name="user[preference]">
  <option value="ducks">
    Ducks
  </option>
  <option value="cats">
    Cats
  </option>
</select>
"""

Select box with prompt

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_select form={@form} field={:week} options={1..2} prompt={"Choose a week number"}/>
...> """
"""
<label for="user_week">
  Week
</label>
<select id="user_week" name="user[week]">
  <option value="">
    Choose a week number
  </option>
  <option value="1">
    1
  </option>
  <option value="2">
    2
  </option>
</select>
"""

Renders <textarea> elements, with the associated <label>s, and any errors for that field.

Attributes

  • hidden_label - Only show the label for screen readers if set to true.
  • All options from above (see top level module doc).
  • All other attributes will be passed onto the textarea element.

See the bitstyles textarea docs for examples of textareas and labels in use.

Textarea

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_textarea form={@form} field={:about_me} />
...> """
"""
<label for="user_about_me">
  About me
</label>
<textarea id="user_about_me" name="user[about_me]">
</textarea>
"""

Textarea

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_textarea form={@form} field={:about_me} required/>
...> """
"""
<label for="user_about_me">
  About me
  <span aria-hidden="true" class="u-fg-warning u-margin-xxs-left">
    *
  </span>
</label>
<textarea id="user_about_me" name="user[about_me]" required="required">
</textarea>
"""

Textarea with options

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_textarea
...>   form={@form}
...>   field={:metadata}
...>   label="Metadata"
...>   label_opts={[class: "extra"]}
...>   value="Value here"
...>   rows={10}
...> />
...> """
"""
<label for="user_metadata" class="extra">
  Metadata
</label>
<textarea id="user_metadata" name="user[metadata]" rows="10">
  Value here
</textarea>
"""

Textarea with hidden label

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_textarea form={@form} field={:address} hidden_label/>
...> """
"""
<label for="user_address" class="u-sr-only">
  Address
</label>
<textarea id="user_address" name="user[address]">
</textarea>
"""

Textarea with error

iex> assigns=%{form: form_with_errors()}
...> render ~H"""
...> <.ui_textarea form={@form} field={:name} />
...> """
"""
<label for="user_name">
  Name
</label>
<textarea id="user_name" name="user[name]">
</textarea>
<span class="u-fg-warning" phx-feedback-for="user[name]">
  is too short
</span>
"""
Link to this function

ui_unwrapped_input(assigns)

View Source

Component for rendering custom inputs together with a label and errors.

Attributes

  • hidden_label - Only show the label for screen readers if set to true.
  • All options from above (see top level module doc).

Custom inputs

iex> assigns=%{form: form_with_errors()}
...> render ~H"""
...> <.ui_unwrapped_input form={@form} field={:name} label="Custom">
...>   Custom content
...>   <input type="text" whatever="foo" />
...> </.ui_unwrapped_input>
...> """
"""
<label for="user_name">
  Custom
</label>
Custom content
<input type="text" whatever="foo"/>
<span class="u-fg-warning" phx-feedback-for="user[name]">
  is too short
</span>
"""
Link to this function

ui_wrapped_input(assigns)

View Source

Component for rendering custom wrapped inputs in a label and with errors.

Attributes

  • All options from above (see top level module doc).

Custom wrapped inputs

iex> assigns=%{form: form()}
...> render ~H"""
...> <.ui_wrapped_input form={@form} field={:name} label="Current name">
...>   <input type="checkbox" id="user_name" whatever="foo" />
...> </.ui_wrapped_input>
...> """
"""
<label for="user_name">
  <input type="checkbox" id="user_name" whatever="foo"/>
  Current name
</label>
"""