Skip to content

<error-label> is a web component for simple, declarative, and accessible error labeling.

License

Notifications You must be signed in to change notification settings

willmartian/error-label

Repository files navigation

Built With Stencil

<error-label>

Simple, declarative, accessible error labeling.

<form>
  <label for="email-input">Email</label>
  <input id="email-input" type="email">
  <error-label for="email-input" type="typeMismatch">Not a valid email.</error-label>
</form>

Form validation with descriptive error messages is an annoying task that is necessary in almost every web development project.

The <error-label> custom element builds off of the browser's default <label> element and Constraint Validation API to take the effort out of this common task, allowing developers to stay DRY.

Live Demo on Codepen

The guiding philosopy of this project is that good error labels should require little to no custom JavaScript.

Features

Overview

The <error-label> custom element works much like the default <label> element. Error labels are linked to inputs using the for attribute: <error-label for="inputId"></error-label>

However, error labels are not displayed to the user by default. They are only visible if the error designated in the type attribute has occured: <error-label for="inputId" type="errorId"></error-label>

Default Errors

Without providing any custom errors, the <error-label> component will support all of the default errors defined by the Constraint Validation API:

  • badInput
  • patternMismatch
  • rangeOverflow
  • rangeUnderflow
  • stepMismatch
  • tooLong
  • tooShort
  • typeMismatch
  • valid
  • valueMissing

Example

<form>
  <label for="password-input">Password</label>
  <input id="password-input" type="password" minlength="6">
  <error-label for="password-input" type="tooShort">Your password must be at least 6 characters long.</error-label>
</form>

Custom Error Messages

You can provide any custom message or HTML inside of an <error-label>.

In addition to this, you can also use the {{value}} variable to access the raw user input value, or the {{length}} variable to access its length.

Example

<form>
  <label for="num-input">Enter a number</label>
  <input id="num-input" type="number">
  <error-label for="num-input" type="badInput">{{value}} is not a number.</error-label>
</form>

Custom Error Types

You can also provide your own custom error types by providing a config object to the parent <form> element's data-error-config attribute.

<form data-error-config="errorLabelConfig">
  <label for="name-input">Name</label>
  <input id="name-input">
  <error-label for="name-input" type="badLang">Please don't say that.</error-label>
</form>

<script>
errorLabelConfig = {
  errors: {
    'badLang': target => target.value.includes('butt'),
  }
} 
</script>

Custom errors are added to the config objects error property. Custom errors are represented as functions that return a boolean value, where a truthy return value indicates the error is present.

Returning a non-empty string will use it as the default message for that error:

<form data-error-config="errorLabelConfig">
  <label for="name-input">Name</label>
  <input id="name-input">
  <error-label for="name-input" type="badLang"></error-label>
</form>

<script>
errorLabelConfig = {
  errors: {
    'badLang': target => target.value.includes('butt') ? `Please don't say ${target.value}.` : false,
  }
} 
</script>

Error Groups

Error labels can also be grouped together to avoid repetition. Attributes defined on the group will be inherited by the error labels within.

<label for="email-input2">Error-Group Email</label>
<input id="email-input2" minlength="5" type="email">
<error-label-group for="email-input2">
  <error-label type="typeMismatch">Not a valid email.</error-label>
  <error-label type="tooShort">Way too short buddy!</error-label>
</error-label-group>

Templates

Error groups can also copy content from <template> elements, to allow for reusable default messages.

<template id="default-errors">
  <error-label type="typeMismatch">Not a valid email.</error-label>
  <error-label type="tooShort">Way too short!</error-label>
</template>
<error-label-group template="default-errors" for="email-input"></error-label-group>

Styling

Error labels and groups can be styled using plain CSS:

<style>
  error-label {
    color: red;
    display: block;
    margin: .5em;
    margin-top: 1em;
  }

  error-label:not([hidden])::before {
    content: '* '
  }

  error-label-group {
    display: block;
  }
</style>

Using this component

Include the following at the top of your HTML file:

<script type="module" src="https://unpkg.com/error-label/dist/error-label/error-label.esm.js"></script>

Licenses

Community License

https://www.gnu.org/licenses/gpl-3.0.en.html

Enterprise License

A more permissive enterprise license is also available. Please direct all related inquiries here.