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
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;
- They have different defaults for
align
andfrom
.- They don't allow for arbitrary HTML and always render the given value in a
<span>
element with appropriate styling.
Attributes
type
(:string
) - > The form field's type.Types
dropdown
powered byElemental.DataInput.Dropdown.dropdown/1
.select
powered byElemental.DataInput.Select.select/1
.- Any value supported by
Elemental.DataInput.Input.input/1
.
Defaults to
"text"
.for
(Phoenix.HTML.FormField
) - Allows for more seamless integration into Elixir forms.Used to determine the
name
,value
, anderrors
fields when building the field.If set the fields
name
,value
, anderrors
are ignored.name
(:string
) - The name of the field, if not given a random value is selected.Ignored of
for
attribute is set.value
(:any
) - The value of the field, must either be a string or a list of string.Ignored of
for
attribute is set.Types
dropdown
- as defined inElement.Dropdown.dropdown/1
select
- as defined inElement.Select.select/1
- Otherwise as defined in
Element.Input.input/1
errors
(:list
) - A list of errors to render in the field, these values will be passed through theerror-translator
attribute.Ignored of
for
attribute is set.Defaults to
[]
.error-translator
({:fun, 1}
) - A function of single arity used to allow errors to be translated by consumer. Defaults toFunction.identity/1
.Translator must return a string, or other HTML safe values as an outcome as the result will be rendered inside a
<span>
.Defaults to
&Function.identity/1
.disable-validator
(:boolean
) - Disables the validator component on the field. Defaults tofalse
.color
(:string
) - The fields's color.Must be one of"ghost"
,"neutral"
,"primary"
,"secondary"
,"accent"
,"info"
,"success"
,"warning"
, or"error"
.size
(:string
) - The fields's size.Must be one of"xs"
,"sm"
,"md"
,"lg"
, or"xl"
.class
(:string
) - Additional CSS classes to pass to the field. Defaults tonil
.multi
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults tofalse
.searchable
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults tofalse
.searchable-inline
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults tofalse
.hover
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults tofalse
.open
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults tofalse
.align
(:string
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults to"start"
.from
(:string
) - SeeElemental.DataInput.Dropdown.dropdown/1
. Defaults to"bottom"
.checked
(:boolean
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.list
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.max
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.maxlength
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.min
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.minlength
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.pattern
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.placeholder
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.readonly
(:boolean
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.step
(:string
) - SeeElemental.DataInput.Input.input/1
. Defaults tonil
.multiple
(:boolean
) - SeeElemental.DataInput.Dropdown.dropdown/1
andElemental.DataInput.Input.input/1
.options
(:list
) - SeeElemental.DataInput.Dropdown.dropdown/1
andElemental.DataInput.Select.select/1
.prompt
(:string
) - SeeElemental.DataInput.Dropdown.dropdown/1
andElemental.DataInput.Select.select/1
. Defaults tonil
.
Slots
overlay
- Allows for inserting inner components that make up thefield
, useful for labeling or other customizations around the field itself.Accepts attributes:align
(:string
) - Alignment of the label, defaults tostart
.Must be one of"start"
, or"end"
.from
(:string
) - The placement of the label relative to other overlays, defaults tocenter
.Must be one of"edge"
, or"center"
.
label
- A shorthand foroverlay
s meant for labeling, changes defaults and simplifies things by defaulting the label class.Effectively a shorthand for;
Accepts attributes:<:overlay> <span class="label">{@value}</span> </:overlay>
value
(:string
) (required) - The value to display in the label.align
(:string
) - Alignment of the label, defaults tostart
.Must be one of"start"
, or"end"
.from
(:string
) - The placement of the label relative to other overlays, defaults toedge
.Must be one of"edge"
, or"center"
.