Elemental.DataInput.Field (elemental v0.3.0)

Building on top of Elemental.DataInput.Input, Elemental.DataInput.Dropdown, and Elemental.DataInput.Select, provide a wrapped component that easy to and decorate as needed.

Usage

<.field /> # simple text input as a field
<.field type="dropdown" prompt="My prompt" /> # now it's a prompt

Fields are mostly intended for use with forms, and they offer simple integration (similar to Phoenix' generated core components);

<.form for={@form} phx-change="change" phx-submit="submit">
  <.field for={@form[:my_field]} type="dropdown" prompt="My prompt" />
</.form>

Labels can be provided to a field as slots configuring them;

# A text field with a label
<.field>
  <:label value="My label"/>
</.field>
# Labels can be place at the end of the field too
<.field>
  <:label value="My label" align="end"/>
</.field>

More complex patterns are supported using "overlays", an overlay is HTML passed externally into the component;

<.field type="email" placeholder="email@example.org">
  <:overlay>
    <svg class="h-[1em] opacity-50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><g stroke-linejoin="round" stroke-linecap="round" stroke-width="2.5" fill="none" stroke="currentColor"><rect width="20" height="16" x="2" y="4" rx="2"></rect><path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7"></path></g></svg>
  </:overlay>
</.field>

Implementation

The input itself is rendered within a <label> element and wrapped with configurable overlays allowing for external customizability. Details on overlay documentation and overall field structure see Elemental.DataInput.Field.field/1.

All attributes defined in Elemental.DataInput.Input.input/1, Elemental.DataInput.Dropdown.dropdown/1, and Elemental.DataInput.Select.select/1 are supported by fields and are just passed over to their respective implementation.

Summary

Functions

The primary form field component.

Functions

field(assigns)

The primary form field component.

This component wraps Elemental.DataInput.Input, Elemental.DataInput.Dropdown, and Elemental.DataInput.Select in a label and offers simplified customizability and form integration.

The component can be configured via overlays passed as slots from the external consumers of it. Overlays allow for inserting HTML element to customize the field.

Structure

The general structure of the render HTML follows

<div>
  <label class="component classes">
    <%# Overlays defined as align="start" from="edge" %>
    <%# Overlays defined as align="start" from="center" %>
    <%# The actual field, be it input, dropdown, or select %>
    <%# Overlays defined as align="end" from="center" %>
    <%# Overlays defined as align="end" from="edge" %>
  </label>
  <span :for={error <- @errors} class="hidden validator-hint">{error}</span>
</div>

Overlays are rendered in the order they appear in the align/from position configured for them, labels are treated the same as overlays are follow the same rules.

Labels are nothing more than a shorthand helper for overlays that;

  1. They have different defaults for align and from.
  2. They don't allow for arbitrary HTML and always render the given value in a <span> element with appropriate styling.

Attributes

Slots

  • overlay - Allows for inserting inner components that make up the field, useful for labeling or other customizations around the field itself.Accepts attributes:
    • align (:string) - Alignment of the label, defaults to start.Must be one of "start", or "end".
    • from (:string) - The placement of the label relative to other overlays, defaults to center.Must be one of "edge", or "center".
  • label - A shorthand for overlays meant for labeling, changes defaults and simplifies things by defaulting the label class.Effectively a shorthand for;
    <:overlay>
      <span class="label">{@value}</span>
    </:overlay>
    Accepts attributes:
    • value (:string) (required) - The value to display in the label.
    • align (:string) - Alignment of the label, defaults to start.Must be one of "start", or "end".
    • from (:string) - The placement of the label relative to other overlays, defaults to edge.Must be one of "edge", or "center".