Email field

The Mishka Chelekom email field is a Phoenix LiveView component for entering an email address. It renders an <input type="email">, so the browser checks the format of the address and phones show an email keyboard. Around the input it adds an optional label, a description, error messages, a floating label and two slots for icons or other content.

It shares the color, variant, size and spacing props of the other form fields, so a form looks the same whichever fields it holds. The examples below show each prop on its own. The first field has a label above the input and the second one a floating label.

<.email_field
  name="email"
  label="Email address"
  placeholder="[email protected]"
  description="We send the receipt to this address."
/>
<.email_field
  name="email"
  label="Email address"
  floating="outer"
  description="We send the receipt to this address."
  size="large"
/>

The variant prop sets the look of the field. The values are base (the default), outline, default, shadow, bordered and transparent. The base variant is a white field with a light border and ignores color. outline draws the border and the text in the chosen color, and default fills the field with it. shadow fills the field and adds a colored shadow. bordered uses a light tint of the color with a border, and transparent has neither fill nor border. Every variant has its own dark mode colors.

<.email_field variant="base" color="primary" />
<.email_field variant="outline" color="primary" />
<.email_field variant="default" color="primary" />
<.email_field variant="shadow" color="primary" />
<.email_field variant="bordered" color="primary" />
<.email_field variant="transparent" color="primary" />

The color prop picks the color of the border, the fill or the text, depending on the variant, and the color of the focus ring. The values are natural (the default), primary, secondary, success, warning, danger, info, misc, dawn, silver, white and dark. The white and dark colors exist for the default and bordered variants.

<.email_field variant="default" color="natural" />
<.email_field variant="default" color="primary" />
<.email_field variant="default" color="success" />
<.email_field variant="default" color="warning" />
<.email_field variant="default" color="danger" />
<.email_field variant="default" color="dark" />

The size prop sets the height of the input. extra_small is 2rem high and extra_large, the default, is 3rem high. small, medium and large sit in between.

<.email_field size="extra_small" />
<.email_field size="small" />
<.email_field size="medium" />
<.email_field size="large" />
<.email_field size="extra_large" />

The rounded prop sets the corner radius of the field. The values are none, extra_small, small (the default), medium, large, extra_large and full.

<.email_field rounded="none" />
<.email_field rounded="extra_small" />
<.email_field rounded="small" />
<.email_field rounded="medium" />
<.email_field rounded="large" />
<.email_field rounded="extra_large" />
<.email_field rounded="full" />

The border prop sets the border width. The values are none, extra_small (1px, the default), small (2px), medium (3px), large (4px) and extra_large (5px). The default, shadow and transparent variants have no border, so the prop changes the base, outline and bordered variants.

<.email_field border="none" />
<.email_field border="extra_small" />
<.email_field border="small" />
<.email_field border="medium" />
<.email_field border="large" />
<.email_field border="extra_large" />

The space prop sets the vertical space between the label, the description, the input and the error messages. The values are none, extra_small, small, medium (the default), large and extra_large.

<.email_field space="extra_small" />
<.email_field space="small" />
<.email_field space="medium" />
<.email_field space="large" />
<.email_field space="extra_large" />

The label prop adds a label above the input, and description adds a short help text under the label. Give the component an id, or pass a field, so the label is linked to the input. The description text is 12px by default, and description_class changes that.

<.email_field
  id="email"
  name="email"
  label="Email address"
  description="We send the receipt to this address."
/>

The floating prop moves the label into the field. The values are none (the default), inner and outer. The label starts inside the field in place of the placeholder and moves up when the field gets focus or a value. With outer it settles on the top edge of the field, and with inner it stays inside the field above the text. A floating field does not show the placeholder prop, and its description sits above the field.

<.email_field floating="inner" variant="default" color="primary" />
<.email_field floating="outer" variant="outline" color="primary" />

The start_section and end_section slots put content before and after the input, inside the border of the field. An icon is the usual choice, and the icon component draws Heroicons by name. Both slots take a class attribute for their wrapper.

<.email_field name="email" label="Email address" placeholder="[email protected]">
  <:start_section>
    <.icon name="hero-envelope" class="size-4" />
  </:start_section>
</.email_field>
<.email_field name="email" label="Email address" placeholder="[email protected]">
  <:end_section>
    <.icon name="hero-envelope" class="size-4" />
  </:end_section>
</.email_field>

Add the multiple attribute to let the user enter several addresses separated by commas. The browser checks each address on its own, and the form sends the value as one string.

<.email_field name="recipients" label="Recipients" multiple />

The ring prop is a boolean and true by default. It draws a thin ring around the field while the input has focus. Set ring={false} to remove it.

<.email_field ring={true} />
<.email_field ring={false} />

Other attributes go straight to the input. The email field passes autocomplete, autofocus, disabled, form, list, maxlength, minlength, multiple, pattern, readonly, required, spellcheck and title, along with aria-* attributes and the global HTML attributes Phoenix allows. For an address field, autocomplete="email" lets the browser fill in a saved address.

<.email_field name="email" label="Required" autocomplete="email" required />
<.email_field name="email" label="Disabled" value="[email protected]" disabled />
<.email_field name="email" label="Read only" value="[email protected]" readonly />

Besides class, which styles the outer element, each part of the field has a prop that takes classes: input_class for the input, label_class for the label, description_class for the description, description_wrapper_class for the box that holds the label and the description, field_wrapper_class for the bordered box around the input and its sections, and floating_label_class for a floating label.

<.email_field label="Email address with custom classes" label_class="text-rose-400" input_class="font-bold" />

Pass a form field with field={@form[:email]} and the component reads its id, name and value from it. The error messages of the field show under the input once the user has used it, and they go through the errors domain of your app's Gettext backend. Without a form, set name and value yourself and pass errors a list of messages. The error_icon prop names a Heroicon that is shown beside each message.

<.email_field field={@form[:email]} label="Email address" error_icon="hero-exclamation-circle" />

<.email_field name="email" value="" errors={["Enter a valid email address"]} />