Telephone Field

The Mishka Chelekom tel field is a Phoenix LiveView component for telephone numbers. It renders an <input type="tel">, which opens the dial pad on phones. Around the input it adds an optional label, a description, error messages, a floating label and two slots for icons or other content.

Phone numbers have no single format, so the browser does not check the value of a tel input by itself. The pattern section below shows how to describe the numbers you accept. The field shares its color, variant, size and spacing props with the other form fields.

<.tel_field
  name="phone"
  label="Phone number"
  placeholder="+1 555 123 4567"
  description="Include the country code."
/>
<.tel_field
  name="phone"
  label="Phone number"
  floating="outer"
  description="Include the country code."
  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.

<.tel_field variant="base" color="primary" />
<.tel_field variant="outline" color="primary" />
<.tel_field variant="default" color="primary" />
<.tel_field variant="shadow" color="primary" />
<.tel_field variant="bordered" color="primary" />
<.tel_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.

<.tel_field variant="default" color="natural" />
<.tel_field variant="default" color="primary" />
<.tel_field variant="default" color="success" />
<.tel_field variant="default" color="warning" />
<.tel_field variant="default" color="danger" />
<.tel_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.

<.tel_field size="extra_small" />
<.tel_field size="small" />
<.tel_field size="medium" />
<.tel_field size="large" />
<.tel_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.

<.tel_field rounded="none" />
<.tel_field rounded="extra_small" />
<.tel_field rounded="small" />
<.tel_field rounded="medium" />
<.tel_field rounded="large" />
<.tel_field rounded="extra_large" />
<.tel_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.

<.tel_field border="none" />
<.tel_field border="extra_small" />
<.tel_field border="small" />
<.tel_field border="medium" />
<.tel_field border="large" />
<.tel_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.

<.tel_field space="extra_small" />
<.tel_field space="small" />
<.tel_field space="medium" />
<.tel_field space="large" />
<.tel_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.

<.tel_field
  id="phone"
  name="phone"
  label="Phone number"
  description="Include the country code."
/>

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.

<.tel_field floating="inner" variant="default" color="primary" />
<.tel_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.

<.tel_field name="phone" label="Phone number" placeholder="+1 555 123 4567">
  <:start_section>
    <.icon name="hero-phone" class="size-4" />
  </:start_section>
</.tel_field>
<.tel_field name="phone" label="Phone number" placeholder="+1 555 123 4567">
  <:end_section>
    <.icon name="hero-phone" class="size-4" />
  </:end_section>
</.tel_field>

A tel input accepts any text, so use pattern to describe the numbers you accept and title to explain the format in the validation message. The browser checks the pattern when the form is submitted. inputmode changes the keyboard a phone shows: inputmode="numeric" gives a number pad with digits only, which suits a local number without a plus sign.

Use minlength and maxlength to limit the length.

<.tel_field name="phone" label="Phone number" pattern="[0-9 +]+" title="Digits, spaces and a plus sign only" />
<.tel_field name="phone" label="Local number" inputmode="numeric" maxlength="10" />

The start section can hold a fixed dialing code or a small select with country codes. A select placed here is a separate form control, so give it its own name to send the code with the form.

<.tel_field name="phone" label="Dialing code as text">
  <:start_section>
    <span class="text-sm ps-1">+1</span>
  </:start_section>
</.tel_field>

<.tel_field name="phone" label="Dialing code as a select">
  <:start_section>
    <select name="country_code" title="Country code" class="bg-transparent text-sm focus:outline-none">
      <option>+1</option>
      <option>+44</option>
      <option>+49</option>
    </select>
  </:start_section>
</.tel_field>

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.

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

Other attributes go straight to the input. The tel field passes autocomplete, autofocus, disabled, form, inputmode, list, maxlength, minlength, pattern, readonly, required and title, along with aria-* attributes and the global HTML attributes Phoenix allows. Use autocomplete="tel" so the browser can fill in a saved number.

<.tel_field name="phone" label="Required" autocomplete="tel" required />
<.tel_field name="phone" label="Disabled" value="+1 555 123 4567" disabled />
<.tel_field name="phone" label="Read only" value="+1 555 123 4567" 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.

<.tel_field label="Phone number with custom classes" label_class="text-rose-400" input_class="font-bold" />

Pass a form field with field={@form[:phone]} 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.

<.tel_field field={@form[:phone]} label="Phone number" error_icon="hero-exclamation-circle" />

<.tel_field name="phone" value="" errors={["Enter a phone number"]} />