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 withBitstylesPhoenix.Component.Form.ui_raw_label/1
.
For details on how to render a form, see:
simple_form
core component in a freshly-generated Phoenix app, orPhoenix.Component.form/1
, orPhoenix.HTML.Form.form_for/4
if using phoenix_html v3 or phoenix_html_helpers
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 totype="text"
.hidden_label
- Only show the label for screen readers if set totrue
.- All options from above (see top level module doc).
- All other attributes will be passed onto the input element.
Defaults to
maxlength="255"
foremail
,text
andpassword
type. Set maxlength tofalse
to prevent setting maxlength.
Types
This function accepts all HTML input types, considering that:
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.
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
- aPhoenix.HTML.FormField
struct retrieved from the form, for example: @form[:email]type
- string or atom, defaults to :textid
- string, required iffield
not passedname
- string, required iffield
not passedvalue
- any, required iffield
not passedchecked
- boolean, required iftype="checkbox"
options
- list, required iftype="select"
multiple
- boolean, used iftype="select"
prompt
- string, used iftype="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 totrue
.options
- The options passed toPhoenix.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 totrue
.- 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>
"""
Component for rendering custom inputs together with a label and errors.
Attributes
hidden_label
- Only show the label for screen readers if set totrue
.- 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>
"""
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>
"""