loki Documentation

Reference - Field arguments

A Loki_FieldComponents block is a block that is defined within the XML layout by referring to the PHTML template Loki_FieldComponents::field.phtml and accompanied with various required or optional arguments.

<block name="yireo-training.example-field" template="Loki_FieldComponents::field.phtml">
    <arguments>
        <argument name="foo" xsi:type="string">bar</argument>
    </arguments>
</block>

Extending from Loki Components

A Loki Field Component is a Loki Component. Because of this, all XML layout arguments of Loki Components apply to Loki Field Components as well.

See Reference - Component arguments

XML layout base arguments

A field block can be supplied with the following XML arguments:

field_type (string, default: text)

A reference to the field type defined as part of the PHP class Loki\Field\Field\FieldTypeManager its constructor argument $fieldTypes. If a field type is given in the XML layout, while there is no valid type available, an error is given.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_type" xsi:type="string">textarea</argument>
    </arguments>
</block>

Example types:

  • input
  • text
  • checkbox
  • password
  • password_repeat
  • radio
  • range
  • select
  • switch
  • textarea

input_type (string, default: text)

If the field_type is allowing for this (like with text), this argument allows setting the type (like with <input type="text">).

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_type" xsi:type="string">input</argument>
        <argument name="input_type" xsi:type="string">email</argument>
    </arguments>
</block>

Example types:

  • text
  • hidden
  • email
  • ...

option_model (instance of Loki\Field\Util\OptionModelInterface)

When the field_type is select, this argument supplies the select options.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_type" xsi:type="string">select</argument>
        <argument name="option_model" xsi:type="object">LokiCheckout\Core\ViewModel\OptionModel\YesNoOptionModel</argument>
    </arguments>
</block>

Example types:

  • text
  • hidden
  • email
  • ...

field_name (string)

The name of a specific field (as in: <input name="foobar">). If it is empty, the last part of the blocks XML layout name is used instead (separate by dots). For example, if the block name is yireo-training.example-field, the name would become example-field.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_name" xsi:type="string">example</argument>
    </arguments>
</block>

field_label (string)

The label of a specific field.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_label" xsi:type="string">Hello World</argument>
    </arguments>
</block>

show_field_label (boolean, default true)

A boolean to allow for hiding the field label.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="show_field_label" xsi:type="boolean">false</argument>
    </arguments>
</block>

field_template (string)

By default, the Loki_FieldComponents::form/field.phtml template resolves the actual field template via the configured field_type. This argument allows you to override the field template on a per-block basis.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_template" xsi:type="string">YireoTraining_Example::form/field/custom.phtml</argument>
    </arguments>
</block>

field_attributes (array)

An array of field attributes added to the field (for example, <input>).

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_attributes" xsi:type="array">
            <item name="" xsi:type="string"></item>
        </argument>
    </arguments>
</block>

In various field-type templates (like Loki_FieldComponents::field/input.phtml), a default is defined:

  • type: text
  • value: Dynamically derived from FieldViewModel::getValue()
  • :value: value (Alpine.js property)
  • @input: setValue (Alpine.js method)
  • @change: submit (Alpine.js method)

Within the FieldViewModel::getFieldAttributes(), this is further extended:

  • id: Dynamically derived from FieldViewModel::getFieldId()
  • aria-label: Field label
  • data-type: field
  • x-ref: field (Alpine.js reference)
  • ...

Possibilities of this argument range from setting additional Alpine.js directives (x-mask, x-data) to configuring specific select attributes (multiple is true).

required (boolean, default false)

A boolean to indicate whether the field is required or not.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="required" xsi:type="boolean">true</argument>
    </arguments>
</block>

disabled (boolean, default false)

A boolean to indicate whether the field is disabled or not.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="disabled" xsi:type="boolean">true</argument>
    </arguments>
</block>

help_text (string)

A help text, commonly shown as a help-icon with a balloon.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="help_text" xsi:type="string">Enter a proper value</argument>
    </arguments>
</block>

comment (string)

A comment, commonly shown underneath the input field.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="comment" xsi:type="string">We hope you like this</argument>
    </arguments>
</block>

placeholder (string)

A placeholder for the text (for <input>, <textarea> and alike).

<block name="yireo-training.example-field">
    <arguments>
        <argument name="placeholder" xsi:type="string">Default value</argument>
    </arguments>
</block>

autocomplete (string)

This argument determines the autocomplete HTML attribute for a field.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="autocomplete" xsi:type="string">shipping address-line1</argument>
    </arguments>
</block>

default_value (string)

A default value for the field. Note that some field types (like a color input) require this to be set.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="field_type" xsi:type="string">input</argument>
        <argument name="input_type" xsi:type="string">color</argument>
        <argument name="default_value" xsi:type="string">#ffffff</argument>
    </arguments>
</block>

js_data (array)

An array of data to be inserted into the Alpine.js component. Note that properties within this array most likely also require the definition of the same property within the Alpine.js component - especially when the property needs to become reactive.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="js_data" xsi:type="array">
            <argument name="example" xsi:type="string">foobar</argument>
        </argument>
    </arguments>
</block>

input_label (string)

Some field types (like checkbox and switch) have both a field_label and an input_label. The input_label is typically shown on the right of the field.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="show_field_label" xsi:type="boolean">false</argument>
        <argument name="field_type" xsi:type="string">switch</argument>
        <argument name="input_label" xsi:type="string">Enable this</argument>
    </arguments>
</block>

use_label_tag (boolean, default true)

If enabled, the label element is created with an HTML tag <label>. If disabled, a <span> is used instead. This is useful when you are creating the <label> in a different way.

<block name="yireo-training.example-field">
    <arguments>
        <argument name="use_label_tag" xsi:type="boolean">false</argument>
    </arguments>
</block>
Last modified: January 29, 2026