«label» Component Type

The label component is an enhancement of the HTML <label> element. It provides better support for accessibility and field association, features SmarkForm features like relative paths, and intelligent defaults.

📖 Table of Contents

* [Overview](#overview)
* [Details](#details)
* [Targetting non scalar fields](#targetting-non-scalar-fields) * [myForm$$ .button:hover {](#myform-buttonhover-) * [myForm$$ .button:active {](#myform-buttonactive-)
* [Options](#options)
* [API Reference](#api-reference)

Overview

Enhanced SmarkForm label elements work similarly to standard HTML labels but offer greater flexibility and automation:

Explicit Association: Use the target property (instead of for). Specify a relative path to the field—typically its name.
Implicit Association: No need to specify target. SmarkForm automatically associates the <label> with the nearest field.
Nested Association: You can nest the field inside the <label> itself, just like in standard HTML (do not use target in this case).

Examples:

🔗

🗒️ HTML

⚙️ JS

👁️ Preview

📝 Notes

<div id="myForm" data-smark='{"focus_on_click":false}'>

    <h2>Explicit association</h2>
    <label data-smark>Click me!</label>
    <span><!-- Intermediate DOM nodes are transparent to SmarkForm's fields tree -->
        <input type="text" data-smark name="field01" placeholder="...and focus will come here">
    </span>
    <p>📌 Label propperly guesses the more appropriate target, even though the intermediate <code>&lt;span&gt;</code>.</p>

    <h2>Explicit target specification</h2>
    <label data-smark='{"target":"field02"}'>Click me!</label>
    <input data-smark name="not_field02" placeholder="(skipped)">
    <input data-smark name="field02" placeholder="...and focus will come here">
    <p>📌 Explicit target specified by relative path.</p>

    <h2>Implicit pairing</h2>
    <label data-smark>Click me!
        <input data-smark name="field03" placeholder="...and focus will come here">
    </label>
    <p>📌 Wrapping the field inside still works likewise standard HTML.</p>

</div>

const myForm = new SmarkForm(document.getElementById("myForm"));

Explicit association

Click me!

📌 Label propperly guesses the more appropriate target, even though the intermediate <span>.

Explicit target specification

Click me!

📌 Explicit target specified by relative path.

Implicit pairing

Click me!

📌 Wrapping the field inside still works likewise standard HTML.

👉 In this example, we’ve set formOptions='{"focus_on_click":false}' to avoid interfering with the demonstration of the label’s behavior since, if enabled (default), it would cause the first field to be focused when clicking anywere in the form (except for actual fields and labels) masking the actual behavior of the first label.

Details

Accessibility Enhancements: Automatically sets for attributes and generates unique IDs to the targetted field when necessary.
Automatic Pairing: Automatically associates with the next field in the DOM.
- Default behavior correctly resolves the target in most cases, reducing manual configuration.
Custom Targeting: Use the target property to explicitly specify which field to associate with when needed.
- Supports absolute and relative paths (see From Traversing.
Implicit Pairing: Implicit pairing (nesting the field inside the label) is supported.
- The target property MUST NOT be used in this case.
- Only one field can be nested inside a label.
- Triggers are allowed inside label elements with no restriction.
Limitations: Labels are only compatible with native HTML input elements (scalars), not complex components or lists.
Selectable Text: The allow_select option controls whether label text can be selected; default is false for better UX.

Targetting non scalar fields

Scalar fields are built on top (or wrapping them in case of the singleton pattern) of native HTML form controls like <input>, <select>, and <textarea>. These elements can be natively associated with a <label> element using the standard HTML mechanisms. SmarkForm only aids in this process by automating the association and enhancing accessibility.

Conversely, non scalar fields wrap multiple SmarkForm fields using other HTML elements that do not support native label association.

Smarkform’s <label> component type extends the labeling capabilities to these complex fields by allowing any HTML element to function as a label, enabling association with complex fields.

To avoid confussion or generating invalid HTML, SmarkForm will complain if a <label> element is used over non-scalar fields.

You can use any other element in place, like <span>, <b> or even <legend>.

In case of <legend>, automatic association is smart enough to target the containing <fieldset> element without further configuration if it is enhanced as SmarkForm field.

Examples:

🔗

🗒️ HTML

🎨 CSS

⚙️ JS

👁️ Preview

📝 Notes

<div id="myForm" data-smark='{"focus_on_click":false}'>

    <h2>Targetting nested forms...</h2>
    <span data-smark='{"type": "label"}'>Click me (auto pairing)!</span>
    <fieldset data-smark name="subform01">
        <input data-smark name="field01" placeholder="First field">
        <input data-smark name="field02" placeholder="Second field">
    </fieldset>
    <span data-smark='{"type": "label"}'>Click me (nested pairing)!
        <fieldset data-smark name="subform02">
            <input data-smark name="field01" placeholder="First field">
            <input data-smark name="field02" placeholder="Second field">
        </fieldset>
    </span>
    <p>📌 <code>&lt;label&gt;</code> tag cannot be used here (See <i>Notes</i> tab).</p>

    <h2>Using &lt;legend&gt;...</h2>
    <fieldset data-smark name="subform03">
        <legend data-smark='{"type": "label"}'>Click me (using legend)!</legend>
        <input data-smark name="field01" placeholder="First field">
        <input data-smark name="field02" placeholder="Second field">
    </fieldset>
    <p>📌 Fieldset's <code>&lt;legend&gt;</code> tags are special case where the containing <code>&lt;fieldset&gt;</code> is automatically targetted.</p>

    <h2>Targetting lists...</h2>
    <fieldset>
        <legend data-smark='{"type": "label"}'>
            <span class="button" title="Add new item" data-smark='{"action":"addItem", "context": "list01"}'>+</span>
            Click me (using legend)!
        </legend>
        <ul data-smark='{"type":"list", "name": "list01"}'>
            <li>
                <input data-smark name="field01" placeholder="First field">
                <input data-smark name="field02" placeholder="Second field">
            </li>
        </ul>
        <span class="button" title="Remove last item" data-smark='{"action":"removeItem", "context": "list01"}'>-</span>
    </fieldset>
    <p>📌 Fieldset's <code>&lt;legend&gt;</code> tags are special case where the containing <code>&lt;fieldset&gt;</code> is automatically targetted.</p>

</div>

#myForm .button {
  display: inline-block;
  padding: 3px 12px;
  margin: 0 4px;
  font-family: system-ui, sans-serif;
  font-size: 14px;
  font-weight: 500;
  text-align: center;
  cursor: pointer;
  border: 1px solid #ccc;
  border-radius: 4px;
  background-color: #f0f0f0;
  color: #333;
  box-shadow: 0 1px 2px rgba(0,0,0,0.1);
  transition: background-color 0.2s;
}

#myForm .button:hover {
  background-color: #e0e0e0;
}

#myForm .button:active {
  background-color: #d0d0d0;
  box-shadow: inset 0 1px 3px rgba(0,0,0,0.2);
}

const myForm = new SmarkForm(document.getElementById("myForm"));

Targetting nested forms...

Click me (auto pairing)!

Click me (nested pairing)!

📌 <label> tag cannot be used here (See Notes tab).

Using <legend>...

Click me (using legend)!

📌 Fieldset's <legend> tags are special case where the containing <fieldset> is automatically targetted.

Targetting lists...

+ Click me (using legend)!

📌 Fieldset's <legend> tags are special case where the containing <fieldset> is automatically targetted.

👉 Notice that, in the case of the list example, the <fieldset> is only stylistic (it has no data-smark attribute), since it has to wrap also list controls to add or remove items that that conceptually goes together with the list itself.

In this case, the <legend> (since the `<fieldset> is not enhanced) correctly targets the list field after itself.

👉 Likewise in the previous one, this example uses formOptions='{"focus_on_click":false}' to avoid interfering with the demonstration of the label’s behavior.

Options

The label component supports several configuration options:

allow_select (boolean, default: false): Controls whether the label text can be selected by the user. When false, sets user-select: none CSS property.
context (string): Specifies the context component for field resolution. Relative paths start from the default context.
target (string): Explicitly specifies which field the label should associate with. Can be a relative or absolute path to the target component.

API Reference

The label component type is primarily a passive enhancement component and does not expose the standard import/export/clear actions that field components provide. Instead, it focuses on:

Field Association: Automatically establishing relationships with form fields
Accessibility Enhancement: Improving screen reader and keyboard navigation support
Action Component Management: Allowing action components (like buttons) to be placed within labels for enhanced user interaction

Labels work by enhancing the DOM structure and relationships rather than managing data, making them fundamentally different from field components that are data-oriented.

⏪

Component Types

«trigger» Component Type

Advanced Concepts

Form Traversing

⏩