Roosevelt

Semantic Forms — Usage

🔝 Scroll to top

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 <script> 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 dist/semantic-forms.css and whichever of the above versions of the JS file you prefer into your project. Both ship in the npm package, and can also be loaded from any CDN that serves npm, for example https://cdn.jsdelivr.net/npm/semantic-forms/dist/semantic-forms.js. The dist folder is built from source, so it is not checked into the git repository.

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).

Forms inside a shadow root

A shadow root is a separate tree, so semanticForms() cannot see into one by default. Pass the root to enhance the forms inside it:

semanticForms(myElement.shadowRoot)

Each tree you pass gets watched separately, so calling it for the document and for one or more shadow roots is fine and they do not interfere with each other. semanticForms.reinitialize(formElement) works out which tree the form belongs to on its own.

Shadow roots do not inherit the page's stylesheets, so the shadow root needs its own copy of the CSS, either through a <link> inside it or by adopting a stylesheet:

const sheet = new CSSStyleSheet()
await sheet.replace(await (await fetch('/path/to/semantic-forms.css')).text())
myElement.shadowRoot.adoptedStyleSheets = [sheet]

Features

Each of these has a page of its own:

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.