URL Field

The Mishka Chelekom url field is a Phoenix LiveView component for web addresses. It renders an <input type="url">, so the browser checks that the value is a complete address such as https://example.com. Around the input it adds an optional label, a description, error messages, a floating label and two slots for icons or other content.

An address without a scheme, like example.com, fails the browser check, and the check runs when the form is submitted. The field shares its color, variant, size and spacing props with the other form fields.

<.url_field
  name="website"
  label="Website"
  placeholder="https://example.com"
  description="Start with https://"
/>
<.url_field
  name="website"
  label="Website"
  floating="outer"
  description="Start with https://"
  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.

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

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

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

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

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

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

<.url_field
  id="website"
  name="website"
  label="Website"
  description="Start with https://"
/>

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.

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

<.url_field name="website" label="Website" placeholder="https://example.com">
  <:start_section>
    <.icon name="hero-link" class="size-4" />
  </:start_section>
</.url_field>
<.url_field name="website" label="Website" placeholder="https://example.com">
  <:end_section>
    <.icon name="hero-link" class="size-4" />
  </:end_section>
</.url_field>

The browser accepts any complete address, including ftp:// or mailto: links. Use pattern to narrow that down, for example to require HTTPS, and title to explain the rule in the validation message.

<.url_field name="website" label="HTTPS only" pattern="https://.*" title="The address must start with https://" />

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.

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

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

<.url_field name="website" label="Required" autocomplete="url" required />
<.url_field name="website" label="Disabled" value="https://example.com" disabled />
<.url_field name="website" label="Read only" value="https://example.com" 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.

<.url_field label="Website with custom classes" label_class="text-rose-400" input_class="font-bold" />

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

<.url_field field={@form[:website]} label="Website" error_icon="hero-exclamation-circle" />

<.url_field name="website" value="" errors={["Enter a full address that starts with https://"]} />