Form elements for HTML-element based systems
Last updated 2 years ago by ungoldman .
Apache-2.0 · Original npm · Tarball · package.json
$ cnpm install form-elements 
SYNC missed versions from official npm registry.



A collection of form elements.


const els = require('form-elements')
const html = require('nanohtml')

const scratch = {
  test: '',
  test2: '',
  pushed: 0

const errOpts = {
  classes: ['error-note'],
  animate: true,
  hiddenState: {
    height: function () {
      let height = this.$errorContainer.clientHeight
      if (this.$errorContainer.children.length === 0) {
        height = '0'
      return `${height}px`
    overflow: 'hidden',
    transition: 'height 0.8s'
  visibleState: {
    height: function () {
      let height = this.$errorContainer.clientHeight
      if (this.$errorContainer.children.length === 0) {
        height = '0'
      return `${height}px`

function main (state, emit) {
  const formErrors = els.error(errOpts)

  const inputOpts = {
    classes: [],
    validate: true,
    errorDisplay: formErrors

  const input2Opts = {
    classes: [],
    required: true,
    validate: true,
    errorDisplay: formErrors

  const $input = els.labeledInput('test email', 'email', oninput, scratch.test, inputOpts)
  const $input2 = els.labeledInput('test required', 'text', oninput2, scratch.test2, input2Opts)

  return html`<div class="">
    <div class="">
      <b>Button pushed:</b> ${scratch.pushed}<br>
      <b>Input value:</b> ${scratch.test}<br>
      ${els.button('i am a button', (evt) => ++scratch.pushed && emit('render'))}

  function oninput (evt) {
    scratch.test = evt.currentTarget.value

  function oninput2 (evt) {
    scratch.test2 = evt.currentTarget.value

Results in:

  <label>Email<br><input type="email" value=""></label>

In this example, the <input type='email'> field will be validated using the built-in browser's validation framework for email addresses. When the user blurs from the field, it'll attempt to validate the data inside, and if it isn't valid, it'll display the error in the <div> located at the top of the form.



All the elements accept an elementOptions hash as the final argument which controls any additional element attributes you may wish to set, in addition to the following:

  • classes:array(string) - an array of class names to apply, in addition to the default ones.
  • style:string - a string containing inline style information

If you wish to override all the classes attached to the input, you can do so by providing the class key on this options list.

Event handlers should be provided using the on[event] key, e.g. oninput or onblur.

Each element type will have specific attributes that can be set in addition to the default attributes provided by the DOM spec.


This is a superset of elementOptions containing the following extra values:

  • animate:boolean: whether or not it should attach style information for CSS animations to show/hide the error element
  • visibleState:object(key:string,value:string|function): what styles to apply to the object when it's visible
  • hiddenState:object(key:string,value:string|function): what styles to apply to the object when it's visible

The valid keys for visibleState and hiddenState are all valid HTML Style rules. You can either set them to a string or a function which returns a sting and runs in the context of the Error element.

  animate: true,
  hiddenState: {
    opacity: 0,
    transition: 'opacity 0.8s ease-in'
  visibleState: {
    opacity: 1,
    height: function () {
      const height = this.$el.clientHeight + 15
      return `${height}px`

The initial state of the object is hiddenState -- these rules will supercede any styles or classes on the object. When errors are presented to the user, it will apply the styles found in visibleState. These will be applyed everytime a new error is presented, allowing you to grow/shrink or otherwise alter the box. When all of the errors are gone, it will apply the hiddenState styles again.



Create a new error display object


  • #render():HTMLDivElement - return a <div> element, using the opts provided by the constructor
  • #displayError(key:string, text:string):undefined - Add a new error to the display
  • #removeError(key:string):undefined - Remove an error from the display
  • #clear():undefined - Remove all errors


input(label:string, type:string, inputHandler:function(evt:HTMLInputEvent, value:(string|number), opts:elementOptions):HTMLInputElement

Create a form input with various options. opts accepts any of the HTMLInputElement attributes, the usual default attributes, in addition to several custom fields:

  • validate:boolean - should validation be attempted when the blur event has been fired
  • validator:function($el:HTMLInputElement):boolean - a custom validation method that returns true/false. If you need to set a custom error message, you should use $el.setCustomValidity, but don't forget to set to an empty string when the error has been resolved!
  • errorDisplay:ErrorElement - the error element that validation errors should be placed into. Must match the API provided by the included error object
<input type=[type] value=[value] oninput=[inputHandler]>

button(text:string, clickHandler:function(evt:HTMLClickEvent), opts:elementOptions):HTMLButtonElement

Create a button with a click handler.

<button onclick=[clickHandler]>[text]</button>

label(text:string, opts:elementOptions):HTMLLabellement

Create a label


labeledInput(label:string, type:string, inputHandler:function(evt:HTMLInputEvent, value:(string|number), labelOpts:elementOptions, inputOpts:elementOptions)

Create a form input element wrapped by a label

<label>[text]<br><input type=[type] value=[value] oninput=[inputHandler]></label>


Copyright © 2018 Scripto, LLC. Licensed under Apache-2.0

Current Tags

  • 2.3.3                                ...           latest (2 years ago)

6 Versions

  • 2.3.3                                ...           2 years ago
  • 2.3.2                                ...           3 years ago
  • 2.3.1                                ...           3 years ago
  • 2.3.0                                ...           4 years ago
  • 2.2.3                                ...           4 years ago
  • 2.2.2                                ...           4 years ago
Today 0
This Week 5
This Month 6
Last Day 1
Last Week 1
Last Month 7
Dependencies (5)
Dev Dependencies (12)
Dependents (0)

Copyright 2014 - 2017 © |