Form • Natura11y Design Ecosystem

Forms are notoriously challenging to style and make accessible. Natura11y provides basic style and behavior for building user friendly, accessible forms.

Form Entries

The form entry parent selector (.form-entry) wraps each entry within a form. Child elements within form entries vary depending on their input types. Such types include text inputs, textareas, selects, checkboxes, and radios.

In Figure 1, the .form-entry selector contains an <input> field with the type="text" attribute.

Form Entry LabelForm entry help text

1
<div class="form-entry">
2

3
    <label class="form-entry__field">
4

5
        <span class="form-entry__field__label">
6
            Form Entry Label
7
        </span>
8

9
        <span class="form-entry__field__input">
10
            <input
11
                type="text"
12
                name="textInputExample"
13
                id="text-input-example"
14
                aria-describedby="help-text-input-example"
15
            />
16
        </span>
17

18
    </label>
19

20
    <small class="form-entry__help" id="help-text-input-example">
21
        Form entry help text
22
    </small>
23

24
</div>

Figure 1

Figure 1 notes
Lines	Details
1	The `.form-entry` parent selector is required. It contains each entries elements, including help text and feedback messages. When more than one `.form-entry` selector is present, spacing between them occurs automatically.
3-18	The `.form-entry__field` child selector is required. It holds the field’s label and input elements. The `.form-entry__field__label` grandchild selector is required. It holds the actual label text, and required indicator (when present). The `.form-entry__field__input` grandchild selector is required. It holds the field’s actual input elements. When using help text, `aria-describedby` is present on the `input` tag for assistive technology. It equals the help text’s `id` attribute (below).
20-22	The `.form-entry__help` child selector is not required. Its id equals its associated `aria-describedby` attribute.

Search Entry

Use the .form-entry--search modifier on the .form-entry element to create an accessible search field. A [data-search-clear] button inside .form-entry__field__input is shown automatically by Natura11y’s JavaScript when the field has a value, and hidden when it is empty.

The label can be visually hidden with .screen-reader-only — a visible label is not required when a leading search icon makes the purpose clear.

1
<div class="form-entry form-entry--search">
2

3
    <label class="form-entry__field">
4

5
        <span class="form-entry__field__label screen-reader-only">
6
            Search
7
        </span>
8

9
        <span class="form-entry__field__input">
10
            <span class="icon icon-search opacity-50" aria-hidden="true"></span>
11
            <input
12
                type="search"
13
                id="search-example"
14
                name="searchExample"
15
            />
16

17
            <button
18
                type="button"
19
                class="button button--icon-only"
20
                data-search-clear
21
                aria-label="Clear search"
22
                aria-controls="search-example">
23
                    <span class="icon icon-clear" aria-hidden="true"></span>
24
            </button>
25

26
            <button type="submit" class="button theme-primary">
27
                Search
28
            </button>
29
        </span>
30

31
    </label>
32

33
</div>

Figure 2

Figure 2 notes
Lines	Details
1	The `.form-entry--search` modifier on `.form-entry` is required. It suppresses the browser’s native clear button on `<input type="search">` so the custom `[data-search-clear]` button is used instead.
10	The leading icon is optional. When present, the input’s `padding-inline-start` is removed automatically so the icon and text align cleanly.
17-24	The `[data-search-clear]` button is required. Natura11y’s JavaScript hides it by default and shows it only when the field has a value. The `aria-controls` attribute must equal the `id` of the associated `<input>`.
26-28	The submit button is optional. Use `type="submit"` when the search field is inside a `<form>` element.

Pre-populated Search (Search Results Page)

When linking to a search results page, pre-apply the has-value class to the .form-entry--search element and set the value attribute on the input to reflect the active query. This ensures the clear button is visible on page load — no JavaScript required for that initial state. It’s a small detail that makes a meaningful difference in usability.

The Search Results Template demonstrates this pattern in a full page layout, including a refined search field, filter sidebar, results list, and pagination.

Select Element

With the example in Figure 3, the same .form-entry container holds a <select> element.

Form Entry LabelForm entry help text

1
<div class="form-entry">
2

3
    <label class="form-entry__field">
4

5
        <span class="form-entry__field__label">
6
            Form Entry Label
7
        </span>
8

9
        <span class="form-entry__field__select">
10
            <select
11
                id="select-example"
12
                name="selectExample"
13
                aria-describedby="help-select-example">
14
                    <option value="">Select</option>
15
                    <option value="Option One">Option One</option>
16
                    <option value="Option Two">Option Two</option>
17
                    <option value="Option Three">Option Three</option>
18
                    <option value="Option Four">Option Four</option>
19
                    <option value="Option Five">Option Five</option>
20
            </select>
21
        </span>
22

23
    </label>
24

25
    <small class="form-entry__help" id="help-select-example">
26
        Form entry help text
27
    </small>
28

29
</div>

Figure 3

Figure 3 notes
Lines	Details
5-7	The `.form-entry__field__label` grandchild selector is required. The label is associated implicitly because the `<label>` element wraps the `<select>` element.
9-21	The `.form-entry__field__select` grandchild selector is required. It holds the actual `<select>` tag. The `<select>` tag’s `id` can be used by help text, validation, and custom scripting.

Text Area

Following the previous example’s pattern, Figure 4 shows the .form-entry parent selector with a <textarea> element.

Form Entry LabelForm entry help text

1
<div class="form-entry">
2

3
    <label class="form-entry__field">
4

5
        <span class="form-entry__field__label">
6
            Form Entry Label
7
        </span>
8

9
        <span class="form-entry__field__input">
10
            <textarea
11
                rows="8"
12
                name="textAreaExample"
13
                id="text-area-example"
14
                aria-describedby="help-textarea-example"
15
            ></textarea>
16
        </span>
17

18
    </label>
19

20
    <small class="form-entry__help" id="help-textarea-example">
21
        Form entry help text
22
    </small>
23

24
</div>

Figure 4

Figure 4 notes
Lines	Details
5-7	The `.form-entry__field__label` grandchild selector is required.
9-16	The `.form-entry__field__input` grandchild selector is required. It holds the actual `<textarea>` tag.

File Upload

Natura11y offers a simple file upload component, as shown in Figure 5 below.

Upload a Single File

Drag and DropBrowse for a File

Form entry help text

1
<div class="form-entry">
2

3
    <div class="form-entry__field">
4

5
        <span class="form-entry__field__label">
6
            Upload a Single File
7
        </span>
8

9
        <div class="form-entry__field__input">
10

11
            <label class="file-upload">
12
                <span class="file-upload__drop">
13
                    <span class="file-upload__drop__text">Drag and Drop</span>
14
                </span>
15

16
                <input class="file-upload__input" type="file" name="fileUploadExample" id="file-upload-example" accept="image/*">
17

18
                <span class="button button--outline file-upload__button">
19
                    <span class="icon icon-upload" aria-hidden="true"></span>
20
                    <span class="text">Browse for a File</span>
21
                </span>
22

23
            </label>
24

25
        </div>
26

27
    </div>
28

29
    <small class="form-entry__help" id="help-file-upload-example">
30
        Form entry help text
31
    </small>
32

33
</div>

Figure 5

Checkboxes

Checkbox (and radio) groups use semantic <fieldset> and <legend> tags. They stack vertically, with a healthy amount of padding. This helps to ensure an accessible target size.

Figure 6 provides the markup required to create a checkbox group.

Form Entry Label

Option One

Option Two

Option Three

1
<div class="form-entry">
2

3
    <fieldset class="form-entry__field">
4

5
        <legend class="form-entry__field__label">
6
            Form Entry Label
7
        </legend>
8

9
        <div class="form-entry__option">
10
          <div class="form-entry__option__check">
11
              <label>
12
                  <input
13
                      type="checkbox"
14
                      name="checkboxGroupExample"
15
                      id="check-option-one"
16
                      value="optionOne">
17
                      <span class="option__label">
18
                          Option One
19
                      </span>
20
              </label>
21
          </div>
22
          <div class="form-entry__option__check">
23
            <label>
24
                <input
25
                    type="checkbox"
26
                    name="checkboxGroupExample"
27
                    id="check-option-two"
28
                    value="optionTwo">
29
                    <span class="option__label">
30
                        Option Two
31
                    </span>
32
            </label>
33
          </div>
34
          <div class="form-entry__option__check">
35
              <label>
36
                  <input
37
                      type="checkbox"
38
                      name="checkboxGroupExample"
39
                      id="check-option-three"
40
                      value="optionThree">
41
                      <span class="option__label">
42
                          Option Three
43
                      </span>
44
              </label>
45
          </div>
46
        </div>
47

48
    </fieldset>
49

50
</div>

Figure 6

Figure 6 notes
Lines	Details
9	The `.form-entry__option` child selector is required. It holds the options markup for the `<fieldset>`.
10	The `.form-entry__option__check` grandchild selector is required. It holds the actual `<label>` and `<input>` tags. The `.form-entry__option__check` selector is repeatable for multiple options.
17-19	The `.option__label` child selector is required. It holds the actual text label for the checkbox.

Single Checkbox

For a single checkbox, do not use a <fieldset> and <legend>. Instead, provide an id on the .form-entry__field__label selector (Figure 7, line 5). Then associate it with aria-labelledby placed on the surrounding <label> tag (Figure 7, line 11).

Form Entry Label

Option

1
<div class="form-entry">
2

3
    <div class="form-entry__field">
4

5
        <span class="form-entry__field__label" id="single-option-label">
6
            Form Entry Label
7
        </span>
8

9
        <div class="form-entry__option">
10
            <div class="form-entry__option__check">
11
                <label aria-labelledby="single-option-label">
12
                    <input
13
                        type="checkbox"
14
                        name="singleOption"
15
                        id="single-option"
16
                        value="option">
17
                        <span class="option__label">
18
                            Option
19
                        </span>
20
                </label>
21
            </div>
22
        </div>
23

24
    </div>
25

26
</div>

Figure 7

Checkbox Switch

Checkboxes can transform into switches with just a couple of of changes to the markup.

First, change .form-entry__option__check to .form-entry__option__switch (Figure 8, line 10). Then, above the option label, add an empty <span> with the .switch__slider class (Figure 8, line 17).

Form Entry Label

Receive Notifications

1
<div class="form-entry">
2

3
    <div class="form-entry__field">
4

5
        <span class="form-entry__field__label" id="switch-option-label">
6
            Form Entry Label
7
        </span>
8

9
        <div class="form-entry__option">
10
            <div class="form-entry__option__switch">
11
                <label aria-labelledby="switch-option-label">
12
                    <input
13
                        type="checkbox"
14
                        name="singleOption"
15
                        id="switch-option"
16
                        value="option">
17
                        <span class="switch__slider"></span>
18
                        <span class="option__label">
19
                            Receive Notifications
20
                        </span>
21
                </label>
22
            </div>
23
        </div>
24

25
    </div>
26

27
</div>

Figure 8

Radios

Like checkboxes, radio groups use semantic <fieldset> and <legend> tags.

Form Entry Label

Option One

Option Two

Option Three

1
<div class="form-entry">
2

3
    <fieldset class="form-entry__field">
4

5
        <legend class="form-entry__field__label">
6
            Form Entry Label
7
        </legend>
8

9
        <div class="form-entry__option">
10
          <div class="form-entry__option__radio">
11
            <label>
12
                <input
13
                    type="radio"
14
                    name="radioGroupExample"
15
                    id="radio-option-one"
16
                    value="optionOne">
17
                    <span class="option__label">
18
                        Option One
19
                    </span>
20
            </label>
21
          </div>
22
          <div class="form-entry__option__radio">
23
            <label>
24
                <input
25
                    type="radio"
26
                    name="radioGroupExample"
27
                    id="radio-option-two"
28
                    value="optionTwo">
29
                    <span class="option__label">
30
                        Option Two
31
                    </span>
32
            </label>
33
          </div>
34
          <div class="form-entry__option__radio">
35
            <label>
36
                <input
37
                    type="radio"
38
                    name="radioGroupExample"
39
                    id="radio-option-three"
40
                    value="optionThree">
41
                    <span class="option__label">
42
                        Option Three
43
                    </span>
44
            </label>
45
          </div>
46
        </div>
47

48
    </fieldset>
49

50
</div>

Figure 9

Figure 9 notes
Lines	Details
9	The `.form-entry__option` child selector is required. It holds each `.form-entry__option__radio` grandchild selector.
10	The `.form-entry__option__radio` grandchild selector is required. It holds the actual `<label>` and `<input>` tags. The `.form-entry__option__radio` selector is repeatable for multiple options.
17-19	The `.option__label` child selector is required. It holds the actual text label for the radio.

Required Fields

Natura11y makes it easy to mark required fields. Add data-required="true" to the parent .form-entry element of the required field. On the same .form-entry element, include a custom error message using the data-error-message={x} attribute. Here x equals the message displayed to the user during the validation process.

Form Entry LabelYour email is required!Example: janeDoe@email.comForm entry help text

1
<div
2
    class="form-entry"
3
    data-required="true"
4
    data-error-message="Custom error message">
5
    <div class="form-entry__field">
6
        ...
7
    </div>
8
</div>

Figure 10

The two data attributes mentioned above are shown in Figure 10, lines 3 and 4. When data-required="true" is present on the .form-entry selector, Natura11y’s JavaScript adds the required attribute to the form entry’s child field automatically.

With the previous example, notice the red asterisk placed before the label. This too, is added automatically to required fields (via Natura11y’s CSS file). The asterisk has become the standard identifier for required fields.

Form Validation

Natura11y provides superficial client-side form validation. Include the novalidate attribute on the <form> tag.

<form data-validate novalidate>

    <div
        class="form-entry"
        data-required="true"
        data-error-message="Username is required!">

        <label class="form-entry__field form-entry__field--float">
            <span class="form-entry__field__label">
                Username
            </span>
            <span class="form-entry__field__input">
                <input type="text" id="account-username" name="accountUsername">
            </span>
        </label>

    </div>

</form>

Figure 11

Floating Labels

For short forms (such as a sign in form) floating labels would be fine to use. Add the .form-entry__field--float modifier class to the .form-entry__field selector (see Figure 12, line 5).

Username

Password

  <div
      class="form-entry"
      data-required="true"
      data-error-message="Username is required!">
      <label class="form-entry__field form-entry__field--float">
          <span class="form-entry__field__label">
              Username
          </span>
          <span class="form-entry__field__input">
              <input type="text" id="account-username" name="accountUsername">
          </span>
      </label>
  </div>

Figure 12

Form styles can be customized by redefining the related CSS custom properties.

:root {
  --form-entry-padding-x: 1em;
  --form-entry-padding-y: var(--button-padding-y);
  --form-entry-target-size: var(--button-target-size);
  --form-entry-border-width: var(--border-width);
  --form-entry-border-color: currentColor;
  --form-entry-border-radius: var(--border-radius-1);
  --form-entry-option-group-border-color: var(--form-entry-border-color);
  --icon-required: "\f14a";
  --icon-checkbox-unchecked: "\f10d";
  --icon-checkbox-checked: "\f10c";
  --icon-radio-unchecked: "\f138";
  --icon-radio-checked: "\f137";
  --icon-disabled: "\f115";
}

Figure 13

Custom property	Default	Purpose
`--form-entry-padding-x`	`1em`	Left and right padding inside form entry controls.
`--form-entry-padding-y`	`var(--button-padding-y)`	Top and bottom padding inside form entry controls.
`--form-entry-target-size`	`var(--button-target-size)`	Minimum target size for form entry controls.
`--form-entry-border-width`	`var(--border-width)`	Border width of form entry inputs, selects, and textareas.
`--form-entry-border-color`	`currentColor`	Border color of form entry inputs, selects, and textareas.
`--form-entry-border-radius`	`var(--border-radius-1)`	Border radius of form entry inputs, selects, textareas, option groups, and file upload controls.
`--form-entry-option-group-border-color`	`var(--form-entry-border-color)`	Border color used for checkbox and radio option groups.
`--icon-required`	`"\f14a"`	Icon unicode used for required field indicators.
`--icon-checkbox-unchecked`	`"\f10d"`	Icon unicode used for unchecked checkboxes.
`--icon-checkbox-checked`	`"\f10c"`	Icon unicode used for checked checkboxes.
`--icon-radio-unchecked`	`"\f138"`	Icon unicode used for unchecked radios.
`--icon-radio-checked`	`"\f137"`	Icon unicode used for checked radios.
`--icon-disabled`	`"\f115"`	Icon unicode used for disabled checkbox and radio options.