Roosevelt

Semantic Forms — usage

Install

npm install semantic-forms

The package is distributed with the following builds available:

  • dist/semantic-forms.cjs: CommonJS bundle: const semanticForms = require('semantic-forms')
  • dist/semantic-forms.js: Standalone bundle that can be included via <script> tags. Declares a global variable called: semanticForms
  • dist/semantic-forms.min.js: Minified standalone bundle that can be included via <p> tags. Declares a global variable called: semanticForms
  • dist/semantic-forms.mjs: ES module: import semanticForms from 'semantic-forms'
  • dist/semantic-forms.min.mjs: Minified ES module: import semanticForms from 'semantic-forms/min'

Use

Include the dist/semantic-forms.css and whichever of the above versions of the JS file you prefer from this repo into your project.

Then apply the semanticForms class to your <form> elements:

<form class="semanticForms">
  <!-- your form here -->
</form>

Then apply the JavaScript enhancements:

semanticForms()

Then the CSS/JS enhancements to your forms will apply automatically, assuming the markup structure you use is one of the supported patterns.

If you make changes to the DOM after Semantic Forms is activated and want to activate any additional semanticForms forms you insert, you can re-scan for new forms by calling semanticForms.reinitialize() again. If you only want to reinitialize one form instead of all of them, call semanticForms.reinitialize(formElement).

Features

Float label inputs

The float label input pattern is notoriously difficult to implement in a fashion that doesn't degrade HTML semantics or accessibility. This pattern library implements a solution that solves that problem. Your label doesn't need to be a sibling of your input like with other implementations. This implementation also has a custom clear button for each input.

Example
<form class="semanticForms">
  <dl>
    <dt><label for="name">Name</label></dt>
    <dd><input id="name" name="name" type="text" placeholder="e.g. John Smith"></dd>
  </dl>
</form>
Or with a <textarea>
<form class="semanticForms">
  <dl>
    <dt><label for="textarea">Textarea</label></dt>
    <dd><textarea id="textarea" name="textarea" rows="5" cols="50" placeholder="e.g. Long string of text"></textarea></dd>
  </dl>
</form>
Add help text

Include a label in the <dd> element with a matching for attribute to place help text beneath the input:

<form class="semanticForms">
  <dl>
    <dt><label for="password">Password</label></dt>
    <dd>
      <input id="password" name="password" type="password" placeholder="Enter a password" minlength="8" required>
      <label for="password">Must be at least 8 characters long.</label>
    </dd>
  </dl>
</form>
Customizing input fields

By default, input fields will display an X icon to clear the text and password fields will also display a show/hide toggle for displaying the password in plain text. You can customize this behavior as follows:

  • Customize the hover text of the clear field button by applying a data-clear-field-text="your text" attribute to the input.

  • Customize the hover text of the show password button by applying a data-show-password-text="your text" attribute to the input.

  • Customize the hover text of the hide password button by applying a data-hide-password-text="your text" attribute to the input.

  • Prevent the show/hide toggle from appearing on password fields by applying a data-no-reveal attribute to the input.

  • Show a help text icon next to labels of inputs that contain a title attribute by applying a data-show-help-icon attribute to the label.

    • Note that checkboxes and radios should have a title attribute on the label instead of the inputs.

Responsive columns

This feature makes it so the form fields will grow, shrink, expand the number of columns, or reduce the number of columns based on how much space exists in the container. You can customize it by applying various colspan-# classes to various elements in the form markup structure.

Set number of columns for a group of forms

You can limit the number of columns on your forms using the colspan-# class on a <dl> element:

<form class="semanticForms">
  <dl class="colspan-2">
    <dt><label for="input-a">Input A</label></dt>
    <dd><input type="text" id="input-a" name="input-a"></dd>

    <dt><label for="input-b">Input B</label></dt>
    <dd><input type="text" id="input-b" name="input-b"></dd>

    <!-- wraps to the next row -->
    <dt><label for="input-c">Input C</label></dt>
    <dd><input type="text" id="input-c" name="input-c"></dd>
  </dl>
</form>

You can also apply the class to a <fieldset> which will apply that styling to all nested <dl> elements:

<form class="semanticForms">
  <fieldset class="colspan-3">
    <!-- inherits 3 column class -->
    <dl>
      <dt><label for="f-ex-input-a">Input A</label></dt>
      <dd><input type="text" id="f-ex-input-a" name="f-ex-input-a"></dd>

      <dt><label for="f-ex-input-b">Input B</label></dt>
      <dd><input type="text" id="f-ex-input-b" name="f-ex-input-b"></dd>

      <dt><label for="f-ex-input-c">Input C</label></dt>
      <dd><input type="text" id="f-ex-input-c" name="f-ex-input-c"></dd>
    </dl>

    <!-- has 4 columns -->
    <dl class="colspan-4">
      <dt><label for="f-ex-input-d">Input D</label></dt>
      <dd><input type="text" id="f-ex-input-d" name="f-ex-input-d"></dd>

      <dt><label for="f-ex-input-e">Input E</label></dt>
      <dd><input type="text" id="f-ex-input-e" name="f-ex-input-e"></dd>

      <dt><label for="f-ex-input-f">Input F</label></dt>
      <dd><input type="text" id="f-ex-input-f" name="f-ex-input-f"></dd>
    </dl>
  </fieldset>
</form>
Set number of columns a single input field takes up

You can specify the number of columns an input will span using the colspan-# class on the <dd> element. The inputs are responsive and will shrink according to available space. Available numbered classes are colspan-1 through colspan-5:

<form class="semanticForms">
  <fieldset>
    <dl>
      <dt><label for="cspan-ex-input-a">Input A</label></dt>
      <!-- 1 column -->
      <dd class="colspan-1"><input type="text" id="cspan-ex-input-a" name="cspan-ex-input-a"></dd>

      <dt><label for="cspan-ex-input-b">Input B</label></dt>
      <!-- 2 columns  -->
      <dd class="colspan-2"><input type="text" id="cspan-ex-input-b" name="cspan-ex-input-b"></dd>

      <dt><label for="cspan-ex-input-c">Input C</label></dt>
      <!-- 5 columns (max) -->
      <dd class="colspan-5"><input type="text" id="cspan-ex-input-c" name="cspan-ex-input-c"></dd>
    </dl>
  </fieldset>
</form>

colspan-full can also be used to force an input to take up the entire width of a form:

<form class="semanticForms">
  <fieldset>
    <dl>
      <dt><label for="cspanfull-ex-input-a">Input A</label></dt>
      <!-- this spans 2 columns on row 1 -->
      <dd class="colspan-2"><input type="text" id="cspanfull-ex-input-a" name="cspanfull-ex-input-a"></dd>

      <dt><label for="cspanfull-ex-input-b">Input B</label></dt>
      <!-- this spans the full width of row 2 -->
      <dd class="colspan-full"><input type="text" id="cspanfull-ex-input-b" name="cspanfull-ex-input-b"></dd>

      <!-- this spans 1 column on row 3 -->
      <dt><label for="cspanfull-ex-input-c">Input C</label></dt>
      <dd><input type="text" id="cspanfull-ex-input-c" name="cspanfull-ex-input-c"></dd>
    </dl>
  </fieldset>
</form>

Button groups

You can align buttons side-by-side, or in left/right/center groups.

Non-grouped example

Nothing fancy here:

<form class="semanticForms">
  <button type="submit" name="submit">Non-grouped submit button</button>
  <button type="submit" name="submit">Another one</button>
</form>
Button groups

Driven by flexbox to intelligently align the buttons based on how many are in the group:

<form class="semanticForms">
  <!-- aligns left/right -->
  <menu>
    <li><button type="submit" name="submit">Button 1</button></li>
    <li><button type="submit" name="submit">Button 2</button></li>
  </menu>

  <!-- aligns left/center/right -->
  <menu>
    <li><button type="submit" name="submit">Button 1</button></li>
    <li><button type="submit" name="submit">Button 2</button></li>
    <li><button type="submit" name="submit">Button 3</button></li>
  </menu>
</form>

    • Checkboxes and radio buttons

    Checkboxes and radio buttons need to follow the following markup structure:

    A single checkbox

    Not too different than other inputs:

    <form class="semanticForms">
  <dl>
    <dt><label for="some_field_name">Single checkbox</label></dt>
    <dd><input type="checkbox" name="some_field_name" id="some_field_name"></dd>
  </dl>
</form>
    Checkbox group
    <form class="semanticForms">
  <dl>
    <dt><label data-for="some_checkboxes">Checkboxes:</label></dt>
    <dd class="checkboxes">
      <ul id="some_checkboxes">
        <li><input type="checkbox" name="some_field_name" id="some_field_name_checkboxes_one"> <label for="some_field_name_checkboxes_one">One</label></li>
        <li><input type="checkbox" name="some_field_name" id="some_field_name_checkboxes_two"> <label for="some_field_name_checkboxes_two">Two</label></li>
        <li><input type="checkbox" name="some_field_name" id="some_field_name_checkboxes_three"> <label for="some_field_name_checkboxes_three">Three</label></li>
      </ul>
    </dd>
  </dl>
</form>
    Radio buttons
    <form class="semanticForms">
  <dl>
    <dt><label data-for="some_radios">Radios:</label></dt>
    <dd class="radios">
      <ul id="some_radios">
        <li><input type="radio" name="some_field_name" id="some_field_name_radios_one"> <label for="some_field_name_radios_one">One</label></li>
        <li><input type="radio" name="some_field_name" id="some_field_name_radios_two"> <label for="some_field_name_radios_two">Two</label></li>
        <li><input type="radio" name="some_field_name" id="some_field_name_radios_three"> <label for="some_field_name_radios_three">Three</label></li>
      </ul>
    </dd>
  </dl>
</form>

    Validation styles

    Inputs with the required attribute will result in a visual indicator (*) being added to its label. You can disable this indicator with the data-no-asterisk attribute on the label element:

    <form class="semanticForms">
  <dl>
    <dt><label for="input" data-no-asterisk>Input label</label></dt>
    <dd><input type="text" name="input" id="input" required>
  </dl>
</form>

    You can set a paragraph of text below a field to only appear when a field is invalid with the data-invalid-text attribute:

    <form class="semanticForms">
  <dl>
    <dt><label for="password_validation">Password label</label></dt>
    <dd>
      <input type="password" name="password" id="password_validation" minlength="8">
      <p data-invalid-text>Password must be at least 8 characters long.</p>
    </dd>
  </dl>
</form>

    Password must be at least 8 characters long.

    You can adjust the tooltip text of the asterisk with the data-asterisk-text attribute:

    <form class="semanticForms">
  <dl>
    <dt><label for="input_validation" data-asterisk-text="This is a custom tooltip.">Input label</label></dt>
    <dd><input type="text" name="input" id="input_validation" required>
  </dl>
</form>

    Light mode and dark mode

    Light mode and dark mode will be detected automatically based on operating system preference. To set it manually, you can apply an additional class of light or dark to your <form> elements to force the mode.

    Low flow (JavaScript disabled) mode

    The low flow will be displayed if JS is disabled.

    You can also activate the low flow (JavaScript disabled) mode manually by adding the lowFlow class to your <form> element.

    The low-flow mode reverts the float label pattern to traditional labels and doesn't include other JS-exclusive enhancements, but preserves the other visual design enhancements driven purely by CSS.

    More

    See a page demoing all features here.