https://github.com/webfactory/cascading-select
Web Component for interdependent <select> form elements, where the available options in a dependent selection list are based on the selection in a parent or control list.
https://github.com/webfactory/cascading-select
web-component
Last synced: 4 months ago
JSON representation
Web Component for interdependent <select> form elements, where the available options in a dependent selection list are based on the selection in a parent or control list.
- Host: GitHub
- URL: https://github.com/webfactory/cascading-select
- Owner: webfactory
- Created: 2025-01-06T19:29:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-13T15:58:25.000Z (about 1 year ago)
- Last Synced: 2025-10-16T09:23:10.824Z (8 months ago)
- Topics: web-component
- Language: JavaScript
- Homepage:
- Size: 16.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
#
Web Component for interdependent `` form elements, where the available options in a dependent selection list are based on the selection in a parent or control list. This pattern is also known as "dependent select" (a subform of the generic "input-dependent input") or "cascading dropdowns".
## Installation
```
npm install @webfactoryde/cascading-select
```
## Usage
The `` Web Component is a lightweight wrapper for standard form markup. If offers complete flexibility in regard to the use of ``, ``, `` and other elements or attributes (i. e. `class`) needed for layout and styling, as long as two `` elements with the necessary (data-) attributes are present.
The second, dependent `` should initially be hidden (via a `hidden` attribute). This way, in case there are JavaScript errors, the parent `` does still offer high-level filtering and only the progressive enhancement of the secondary filter level is missing.
### Steps to implement:
1. The JS file "cascading-select.js" must be loaded. Depending on browser support requirements, transpilation for older browsers is recommended.
2. Two `` elements must be output within the Web Component.
3. The parent `` requires a `data-dependent-id` attribute that contains the `id` of the dependent `` as its value to link the two fields.
4. The ``s of the parent `` that have a sub-selection at the second level require a `data-dependent-options` attribute with a JSON-formatted array of objects, each containing a `label` and `value`. Empty placeholder options must also be listed.
5. The dependent `` requires an `id` attribute with matches the value used for `data-dependent-id` on the parent.
6. The dependent `` should initially have a `hidden` attribute; this will be removed by the Web Component as needed, but serves as a no-JS fallback in case the Web Component does not initialize correctly.
## Parameters
Web Components support common HTML attributes but can also receive custom parameters.
| Option | Type | Default | Description|
|-----------------------|---------|---------|-----------|
| always-show-dependent | boolean | false | Controls initial display of the second ("dependent") `` when no selection is made in the first ("parent") or an option without sub-selection possibilities is selected. Default: the second field is hidden. When the parameter is present, it is displayed and marked with `aria-disabled` (assuming it has no meaningful interactivity until a selection is made in the "parent", but should still be visible to visually indicate the functional pattern).|
## Example
```
Where do you want to go bouldering?
City
Please choose a city
Bonn
Köln
Münster
Gym
```