https://github.com/willmartian/error-label
<error-label> is a web component for simple, declarative, and accessible error labeling.
https://github.com/willmartian/error-label
component customelement error error-label error-messages form forms headless html validation webcomponent webcomponents
Last synced: 23 days ago
JSON representation
<error-label> is a web component for simple, declarative, and accessible error labeling.
- Host: GitHub
- URL: https://github.com/willmartian/error-label
- Owner: willmartian
- License: gpl-3.0
- Created: 2021-05-01T02:09:11.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2021-08-11T19:19:32.000Z (almost 5 years ago)
- Last Synced: 2025-01-17T06:46:30.303Z (over 1 year ago)
- Topics: component, customelement, error, error-label, error-messages, form, forms, headless, html, validation, webcomponent, webcomponents
- Language: TypeScript
- Homepage:
- Size: 65.4 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://stenciljs.com)
# ``
_Simple, declarative, accessible error labeling._
```html
Email
Not a valid email.
```
Form validation with descriptive error messages is an annoying task that is [necessary](https://www.nngroup.com/articles/visibility-system-status/) in almost _every_ web development project.
The `` custom element builds off of the browser's default `` element and [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/API/Constraint_validation) to take the effort out of this common task, allowing developers to stay [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
[**Live Demo on Codepen**](https://codepen.io/willmartian/pen/BaRYvRy)
**The guiding philosopy of this project is that good error labels should require little to no custom JavaScript.**
- [Features](#features)
- [Default Errors](#default-errors)
- [Custom Error Messages](#custorm-error-messages)
- [Custom Error Types](#custrom-error-types)
- [Error Groups](#error-groups)
- [Styling](#styling)
- [Using this component](#using-this-component)
- [Licenses](#licenses)
## Features
### Overview
The `` custom element works much like the default `` element. Error labels are linked to inputs using the `for` attribute: ``
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: ``
### Default Errors
Without providing any [custom errors](), the `` component will support all of the default errors defined by the [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState#properties):
- `badInput`
- `patternMismatch`
- `rangeOverflow`
- `rangeUnderflow`
- `stepMismatch`
- `tooLong`
- `tooShort`
- `typeMismatch`
- `valid`
- `valueMissing`
#### Example
```html
Password
Your password must be at least 6 characters long.
```
### Custom Error Messages
You can provide any custom message or HTML inside of an ``.
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
```html
Enter a number
{{value}} is not a number.
```
### Custom Error Types
You can also provide your own custom error types by providing a config object to the parent `` element's `data-error-config` attribute.
```html
Name
Please don't say that.
errorLabelConfig = {
errors: {
'badLang': target => target.value.includes('butt'),
}
}
```
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:
```html
Name
errorLabelConfig = {
errors: {
'badLang': target => target.value.includes('butt') ? `Please don't say ${target.value}.` : false,
}
}
```
### 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.
```html
Error-Group Email
Not a valid email.
Way too short buddy!
```
#### Templates
Error groups can also copy content from `` elements, to allow for reusable default messages.
```html
Not a valid email.
Way too short!
```
```html
```
### Styling
Error labels and groups can be styled using plain CSS:
```html
error-label {
color: red;
display: block;
margin: .5em;
margin-top: 1em;
}
error-label:not([hidden])::before {
content: '* '
}
error-label-group {
display: block;
}
```
## Using this component
Include the following at the top of your HTML file:
```html
```
### 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.](https://willmartian.com/contact)