Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fboes/formwerk
Web components for improved HTML form elements.
https://github.com/fboes/formwerk
forms webcomponent webcomponents
Last synced: 2 months ago
JSON representation
Web components for improved HTML form elements.
- Host: GitHub
- URL: https://github.com/fboes/formwerk
- Owner: fboes
- License: mit
- Created: 2024-09-01T05:50:15.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-09-14T11:13:31.000Z (3 months ago)
- Last Synced: 2024-10-01T02:41:47.695Z (3 months ago)
- Topics: forms, webcomponent, webcomponents
- Language: TypeScript
- Homepage:
- Size: 121 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Formwerk
Web components for improved HTML form elements.
```html
Example
This is an example text field
```
Refer to the [Formwerk examples page](https://fboes.github.io/formwerk/example/) on live examples as well as their code examples.
These web components exist:
1. `` enhances [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
2. `` enhances [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
3. `` enhances [`` & ``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
4. `` enhances [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
All components have in common that any attributes attached will be attached to the ``, `` or `` field inside of it. There are some additional attributes which will not be attached to the form field elements, but instead will make your live easier by attaching extra DOM structures around the form field element.
## Installation
Either download the [`formwerk.js`](dist/formwerk.js) and [`formwerk.css`](dist/formwerk.css) to a sensible location in your web project, or do a NPM installation:
```bash
npm install @fboes/formwerk --save
```
Instead of a local installation you may also load the library from https://unpkg.com/. Beware: This makes https://unpkg.com/ a dependency of your project and may pose data protection issues.
```html
```
Everything required for the front-end functionality of this web component is contained in [`formwerk.js`](./dist/formwerk.js)and [`formwerk.css`](dist/formwerk.css).
## Usage
Load the JavaScript file [`formwerk.js`](dist/formwerk.js) into your HTML document to enable the Formwerk web components.
```html
```
Optional: Load additional [`formwerk.css`](dist/formwerk.css) style sheet for some basic styling of the Formwerk web components.
```html
```
Write the Formwerk web components tags into your HTML.
```html
```
Refer to the [Formwerk examples page](https://fboes.github.io/formwerk/example/) on live examples as well as their code examples.
Be aware that changing the attributes of the web components after mounting these to the DOM does most often not apply any further changes. Instead change the _properties_ of the web components.
## Attributes
These additional attributes exists on the Formwerk web components:
| Name | Type | Property | `` | `` | `` | `` |
| ------------ | ------------------ | :------: | :------------------: | :-------------------: | :-----------------------: | :---------------------: |
| `label` | string | | ✅ | ✅ | ✅ | ✅ |
| `helptext` | string | | ✅ | ✅ | ✅ | ✅ |
| `output` | boolean | | ✅ | ✅ | | |
| `unit` | string | | ✅ | ✅ | | |
| `required` | boolean | ✅ | ✅ | ✅ | ✅ | ✅ |
| `disabled` | boolean | ✅ | ✅ | ✅ | ✅ | ✅ |
| `options` | string[]\|object[] | ✅ | ✅ | ✅ | ✅ | |
| `values` | string[] | ✅ | ✅ | ✅ | ✅ | |
| `toggletype` | object | | ✅ | | | |
| `autogrow` | boolean | | | | | ✅ |
### `label`
Will spawn an extra `` before the form element, the attribute value will be the label text.
### `helptext`
Will spawn an extra help paragraph text after the form element, the attribute value will be the paragraph text.
### `output`
Will spawn an extra `` after the form element, if set to `true`. This output show the current value, and may be helpful for inputs which do not show the current value like ``.
### `unit`
Will spawn an extra extra unit name (e.g. "°C") text after the form element, the attribute value will be the unit text.
### `required`
Will toggle the input element's attribute `required` and add/remove the class `is-required`.
### `disabled`
Will toggle the input element's attribute `disabled` and add/remove the class `is-disabled`.
### `options`
Instead of creating multiple options for a ``, ``, `` or ``, the `options` property allows for a fast creation of option lists.
This is available as attribute and element property.
A single list of options looks like this:
```json
["One", "Two", "Three"]
```
If you are in need of having values and labels of a options behave differently, you can use a structured array.
```json
[
{ "value": "1", "label": "One" },
{ "value": "2", "label": "Two" },
{ "value": "3", "label": "Three" }
]
```
### `values`
For `` as well as `` it is possible to have multiple selected values for a given input element. For these elements there is a helpful `values` property to set and read multiple `value`.
This is available as attribute and element property.
```json
["One", "Two", "Three"]
```
### `toggletype`
This allows `` field to change their type. The attribute requires the following JSON:
```json
{
"type": "text",
"labelOff": "⇄",
"labelOn": "⇆",
"title": "Show / hide password"
}
```
### `autogrow`
Text areas will grow according to their input text size.
## Classes
```css
.formwerk.is-required {
/* This web component has a required input element */
}
.formwerk.is-disabled {
/* This web component has a disabled input element */
}
.formwerk.is-invalid {
/* This web component has an invalid input element value */
}
```
## Status
[](https://github.com/fboes/formwerk)
[](https://www.npmjs.com/package/@fboes/formwerk)
## Legal stuff
Author: [Frank Boës](https://3960.org/) 2024
Copyright & license: See [LICENSE.txt](LICENSE.txt)