Generates a checkbox.

Wrapper around PhoenixHTMLHelpers.Form.checkbox/3.

<.checkbox name="available_for_hire" />

To create a group of checkboxes, see checkbox_group/1.

Examples

Set the checked state:

<.checkbox name="available_for_hire" checked />

Using the checkbox with form data. This will automatically create the checkbox label:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.checkbox form={f} field={:available_for_hire} />
</.form>

Pass a custom checkbox label with the label slot:

<.checkbox form={:user} field={:available_for_hire}>
  <:label>Some label</:label>
</.checkbox>

Add emphasis to the label:

<.checkbox name="available_for_hire" is_emphasised_label />

Add a hint below the label:

<.checkbox name="available_for_hire">
  <:label>Some label</:label>
  <:hint>
    Add your <strong>resume</strong> below
  </:hint>
</.checkbox>

Reveal extra details when the checkbox is checked:

<.checkbox name="available_for_hire">
  <:label>Some label</:label>
  <:disclosure>
    <span class="d-block mb-1">Available hours per week</span>
    <.text_input is_contrast size="3" />
    <span class="text-small color-fg-muted pl-2">hours per week</span>
  </:disclosure>
</.checkbox>

Attributes

• form (:any) - Either a Phoenix.HTML.Form or an atom. Defaults to nil.

• field (:any) - Field name (atom or string). Defaults to nil.

• name (:string) - Input name attribute (when not using form and field).

• input_id (:string) - When using form/field. Custom input ID to be used in case the generated IDs cause "Multiple IDs detected" errors. Defaults to nil.

• checked (:boolean) - The state of the checkbox (when not using form and field).

• checked_value (:string) - The value to be sent when the checkbox is checked. If checked_value equals value, the checkbox is marked checked. Defaults to "true". Defaults to nil.

• hidden_input (:string) - Controls if the component will generate a hidden input to submit the unchecked checkbox value or not. Defaults to "true". Defaults to "true".

• value (:string) - Checkbox value attribute (overrides field value when using form and field).

• is_multiple (:boolean) - When creating a list of checkboxes. Appends [] to the input name so that a list of values is passed to the form events.

  Alternatively, use checkbox_in_group/1 to set this automatically.

  Defaults to false.

• is_emphasised_label (:boolean) - Adds emphasis to the label. Defaults to false.

• is_omit_label (:boolean) - Omits the label. Defaults to false.

• class (:any) - Additional classname. Defaults to nil.

• classes (:map) - Additional classnames for checkbox elements.

  Any provided value will be appended to the default classname.

  Default map:

  %{
    container: "",       # Checkbox container
    label_container: "", # Input label container
    label: "",           # Input label
    input: "",           # Checkbox input element
    caption: "",         # Hint message element
    hint: "",            # Deprecation support: identical to "caption"
    disclosure: ""       # Disclosure container (inline)
  }

  Defaults to %{input: nil, label: nil, hint: nil, caption: nil, container: nil, label_container: nil, disclosure: nil}.

• Global attributes are accepted. Supports all globals plus: ["disabled"].

Slots

• label - Custom checkbox label. Overides the derived label when using a form and field. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• caption - Adds text below checkbox label. Enabled when a label is displayed. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• hint - Deprecated: use caption. As of 0.5.0. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• disclosure - Extra label content to be revealed when checkbox is checked. Enabled when a label is displayed.Note that the label element can only contain inline child elements.Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)

Reference

• Primer Checkbox
• Primer Checkbox group
• Primer Form control

Checkbox group renders a set of checkboxes.

<.checkbox_group>
  <.checkbox name="roles[]" checked_value="admin" />
  <.checkbox name="roles[]" checked_value="editor" />
</.checkbox_group>

This is equivalent to:

<.form_control is_input_group>
  <.checkbox name="roles[]" checked_value="admin" />
  <.checkbox name="roles[]" checked_value="editor" />
</.form_control>

is_input_group (and hence checkbox_group) adds specific styling: a larger label font size, and layout for inputs, captions and validation.

Examples

Another convenience component - checkbox variant checkbox_in_group/1 - sets attr is_multiple to true, so that the server receives an array of strings for the checked values.

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.checkbox_group
    form={f}
    field={@field}
    caption="Select one"
  >
    <.checkbox_in_group
      :for={{label, value} <- @options}
      form={f}
      field={@field}
      checked_value={value}
      checked={value in @values}
    >
      <:label>
        <%= label %>
      </:label>
    </.checkbox_in_group>
  </.checkbox_group>
</.form>

Reference

Primer Checkbox group

Attributes

• form (:any) - Either a Phoenix.HTML.Form or an atom. Defaults to nil.

• field (:any) - Field name (atom or string). Defaults to nil.

• validation_message (:any) - Function to write a custom validation message (in case of error or success).

  The function receives a PrimerLive.FieldState struct and returns a validation message or nil.

  A validation message is shown:

  • If form is a Phoenix.HTML.Form, containing a changeset
  • The validation_message function does not return nil

  Function signatures:

  • fun () -> string | nil

  • fun (field_state) -> string | nil

  Conditional error message:

  fn field_state ->
    if !field_state.valid?, do: "Please enter your first name"
  end

  Conditional success message, only shown when changeset.action is :validate:

  fn field_state ->
    if field_state.valid? && field_state.changeset.action == :validate, do: "Is available"
  end

  Defaults to nil.

• caption (:any) - Hint message below the checkbox group label.

  Pass a string, or a function that returns a string.

  The function receives a PrimerLive.FieldState struct and returns a message or nil (which omits the caption element).

  Function signatures:

  • fun () -> string | nil

  • fun (field_state) -> string | nil

  To conditionally show a caption, use field_state. To show the caption when field state is valid:

  fn field_state ->
    if !field_state.valid?, do: nil, else: "Caption"
  end

  For additional markup, use the H sigil:

  fn ->
    ~H'''
    Caption with <a href="/">link</a>
    '''
  end

  Defaults to nil.

• label (:string) - Custom label. Note that a label is automatically generated when using field. Defaults to nil.

• is_hide_label (:boolean) - Omits the automatically generated label (when using field). Defaults to false.

• is_disabled (:boolean) - Adjusts the styling to indicate disabled state. Defaults to false.

• required_marker (:string) - Required field marking. This will be shown for all required fields (when using Phoenix.HTML.Form). Pass an empty string to remove the indicator. Defaults to "*".

• class (:any) - Additional classname. Defaults to nil.

• classes (:map) - Additional classnames for checkbox group elements.

  Any provided value will be appended to the default classname.

  Default map:

  %{
    control: "",               # Checkbox group wrapper
    group: "",                 # Deprecation support: identical to "control"
    header: "",                # Header element containing the group label
    label: "",                 # Checkbox group label
    input_group_container: "", # Input group container (for checkbox_group and radio_group)
    caption: "",               # Checkbox group caption
  }

  Defaults to %{control: nil, label: nil, header: nil, group: nil, caption: nil, input_group_container: nil}.

• Global attributes are accepted.

Slots

• inner_block (required) - The checkbox group content.

Convenience checkbox component for use inside checkbox_group/1.

Sets attr is_multiple to true, so that the server receives an array of strings for the checked values.

<.checkbox_in_group form={@form} field={@field} />

Inside a form and checkbox group:

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.checkbox_group
    form={f}
    field={@field}
  >
    <.checkbox_in_group
      :for={{label, value} <- @options}
      form={f}
      field={@field}
      checked_value={value}
      checked={value in @values}
    />
  </.checkbox_group>
</.form>

Attributes

Use checkbox/1 attributes.

Helper component that generates a form control: a wrapper around a form input that maintains consistent layout and a field label. Form control is used by other components, and you probably won't need to use it standalone.

Used with text_input/1, textarea/1 and select/1.

Automatically adds a label based on supplied form and field (with the option to set a custom label) and a required mark if the field is required.

Unlike Primer Style, the form control component does not provide validation messages and captions - these can also be added to the input element without a form control.

Using form_control standalone:

<.form_control field="first_name">
  <.text_input field="first_name" />
</.form_control>

This is equivalent to:

<.text_input field="first_name" is_form_control />

Examples

With a PhoenixHTMLHelpers.Form:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.form_control form={f} field={:first_name}>
    <.text_input
      form={f}
      field={:first_name}
      phx_debounce="blur"
    />
  </.form_control>
</.form>

Custom label:

<.form_control form={f} field={:first_name} label="Enter your first name">
...
</.form_control>

Hide the label:

<.form_control form={f} field={:first_name} is_hide_label>
...
</.form_control>

Attributes

• form (:any) - Either a Phoenix.HTML.Form or an atom. Defaults to nil.

• field (:any) - Field name (atom or string). Defaults to nil.

• is_input_group (:boolean) - Creates styling for checkbox_group/1 and radio_group/1: a larger label font size, and layout for inputs, captions and validation. Defaults to false.

• caption (:any) - Hint message below the form control label.

  Pass a string, or a function that returns a string.

  The function receives a PrimerLive.FieldState struct and returns a message or nil (which omits the caption element).

  Function signatures:

  • fun () -> string | nil

  • fun (field_state) -> string | nil

  To conditionally show a caption, use field_state. To show the caption when field state is valid:

  fn field_state ->
    if !field_state.valid?, do: nil, else: "Caption"
  end

  For additional markup, use the H sigil:

  fn ->
    ~H'''
    Caption with <a href="/">link</a>
    '''
  end

  Defaults to nil.

• label (:string) - Custom label. Note that a label is automatically generated when using field. Defaults to nil.

• is_hide_label (:boolean) - Omits the automatically generated label (when using field). Defaults to false.

• is_disabled (:boolean) - Adjusts the styling to indicate disabled state. Defaults to false.

• required_marker (:string) - Required field marking. This will be shown for all required fields (when using Phoenix.HTML.Form). Pass an empty string to remove the indicator. Defaults to "*".

• class (:any) - Additional classname. Defaults to nil.

• classes (:map) - Additional classnames for form control elements.

  Any provided value will be appended to the default classname.

  Default map:

  %{
    control: "",               # Form control wrapper
    group: "",                 # Deprecation support: identical to "control"
    header: "",                # Header element containing the group label
    label: "",                 # Form control label
    input_group_container: "", # Input group container (for checkbox_group and radio_group)
    caption: "",               # Form control caption
  }

  Defaults to %{control: nil, label: nil, header: nil, group: nil, caption: nil, input_group_container: nil}.

• deprecated_has_form_group (:boolean) - Internal use: detects if deprecated form_group or is_form_group is used. Used to maintain consistent styling. Defaults to false.

• for (:string) - Internally used by text_input/1 and textarea/1 when using is_form_control or form_control. Label attribute to associate the label with the input. for should be the same as the input's id. Defaults to nil.

• Global attributes are accepted.

Slots

• inner_block (required) - The form control content.

Reference

Primer Form control

Generates a validation message for a form input. It can be used as standalone component for inputs where the position of the validation feedback is not so obvious.

This component is incorporated in "singular inputs" text_input/1, textarea/1 and select/1.

A validation error message is automatically added when using a changeset with an error state. The message text is taken from the changeset errors.

To show the default validation message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message form={@form} field={:availability} />
</.form>

To show a custom error message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message
    form={@form}
    field={:availability}
    validation_message={
      fn field_state ->
        if !field_state.valid?, do: "Please select your availability"
      end
    }
  />
</.form>

Similarly, to show a custom validation success message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message
    form={@form}
    field={:availability}
    validation_message={
      fn field_state ->
        if field_state.valid?, do: "Great!"
      end
    }
  />
</.form>

Reference

Primer Form control

Attributes

• form (:any) - Either a Phoenix.HTML.Form or an atom. Defaults to nil.

• field (:any) - Field name (atom or string). Defaults to nil.

• input_id (:string) - When using form/field. Custom input ID to be used in case the generated IDs cause "Multiple IDs detected" errors. Defaults to nil.

• validation_message (:any) - Function to write a custom validation message (in case of error or success).

  The function receives a PrimerLive.FieldState struct and returns a validation message or nil.

  A validation message is shown:

  • If form is a Phoenix.HTML.Form, containing a changeset
  • The validation_message function does not return nil

  Function signatures:

  • fun () -> string | nil

  • fun (field_state) -> string | nil

  Conditional error message:

  fn field_state ->
    if !field_state.valid?, do: "Please enter your first name"
  end

  Conditional success message, only shown when changeset.action is :validate:

  fn field_state ->
    if field_state.valid? && field_state.changeset.action == :validate, do: "Is available"
  end

  Defaults to nil.

• validation_message_id (:any) - Message ID that is usually passed from the form element component to input_validation_message. If not used, the ID will be generated.

• is_multiple (:boolean) - Set to true when the validation message refers to a "multiple" field, to that the generated ID will include suffix []. Defaults to false.

• class (:any) - Additional classname. Defaults to nil.

• Global attributes are accepted.

Generates a radio button.

Wrapper around PhoenixHTMLHelpers.Form.radio_button/4.

<.radio_button name="role" value="admin" />
<.radio_button name="role" value="editor" />

To create a group of radio buttons, see radio_group/1.

Examples

Set the checked state:

<.radio_button name="role" value="admin" />
<.radio_button name="role" value="editor" checked />

Using the radio button with form data. This will automatically create the radio button label:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.radio_button form={f} field={:role} value="admin" />
  <.radio_button form={f} field={:role} value="editor" />
</.form>

Pass a custom radio button label with the label slot:

<.radio_button form={:user} field={:role}>
  <:label>Some label</:label>
</.radio_button>

Add emphasis to the label:

<.radio_button name="role" is_emphasised_label />

Add a hint below the label:

<.radio_button name="role">
  <:label>Some label</:label>
  <:hint>
    Add your <strong>resume</strong> below
  </:hint>
</.radio_button>

Reveal extra details when the radio button is checked:

<.radio_button name="role">
  <:label>Some label</:label>
  <:disclosure>
    <span class="d-block mb-1">Available hours per week</span>
    <.text_input is_contrast size="3" />
    <span class="text-small color-fg-muted pl-2">hours per week</span>
  </:disclosure>
</.radio_button>

Attributes

• form (:any) - Either a Phoenix.HTML.Form or an atom. Defaults to nil.

• field (:any) - Field name (atom or string). Defaults to nil.

• name (:string) - Input name attribute (when not using form and field).

• input_id (:string) - When using form/field. Custom input ID to be used in case the generated IDs cause "Multiple IDs detected" errors. Defaults to nil.

• checked (:boolean) - The state of the radio button (when not using form and field).

• checked_value (:string) - For internal use to ensure compatibility with "single select" radio buttons in action_list/1. Defaults to nil.

• value (:string) - Radio button value attribute (overrides field value when using form and field).

• is_emphasised_label (:boolean) - Adds emphasis to the label. Defaults to false.

• is_omit_label (:boolean) - Omits the label. Defaults to false.

• class (:any) - Additional classname. Defaults to nil.

• classes (:map) - Additional classnames for radio button elements.

  Any provided value will be appended to the default classname.

  Default map:

  %{
    container: "",       # Radio button container
    label_container: "", # Input label container
    label: "",           # Input label
    input: "",           # Radio button input element
    caption: "",         # Hint message element
    hint: "",            # Deprecation support: identical to "caption"
    disclosure: ""       # Disclosure container (inline)
  }

  Defaults to %{input: nil, label: nil, hint: nil, caption: nil, container: nil, label_container: nil, disclosure: nil}.

• Global attributes are accepted. Supports all globals plus: ["disabled"].

Slots

• label - Custom radio button label. Overides the derived label when using a form and field. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• caption - Adds text below radio button label. Enabled when a label is displayed. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• hint - Deprecated: use caption. As of 0.5.0. Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)
• disclosure - Extra label content to be revealed when radio button is checked. Enabled when a label is displayed.Note that the label element can only contain inline child elements.Accepts attributes:
  • class (:any) - Additional classname.
  • style (:string) - Additional CSS styles.
  • rest (:any)

Reference

• Primer Radio
• Primer Form control

Radio group renders a set of radio buttons.

<.radio_group>
  <.radio_button name="role" value="admin" />
  <.radio_button name="role" value="editor" />
</.radio_group>

This is equivalent to:

<.form_control is_input_group>
  <.radio_button name="role" value="admin" />
  <.radio_button name="role" value="editor" />
</.form_control>

is_input_group (and hence radio_group) adds specific styling: a larger label font size, and layout for inputs, captions and validation.

Examples

<.form :let={f} for={@changeset}>
  <.radio_group form={f} field={@field} caption="Select one">
    <.radio_button
      :for={{label, value} <- @options}
      form={f}
      field={@field}
      value={value}
    >
      <:label>
        <%= label %>
      </:label>
    </.radio_button>
  </.radio_group>
</.form>