select-pure
Version:
Custom JavaScript <select> component. Easy-to-use, accessible, mobile friendly and super efficient
213 lines (170 loc) • 7.72 kB
Markdown
# Custom JavaScript `<select>` component. Easy-to-use, accessible, mobile friendly and super efficient.
[](https://www.npmjs.com/package/select-pure)
[](https://unpkg.com/select-pure/dist/index.js)
[](https://unpkg.com/select-pure/dist/index.js)
[](https://www.npmjs.com/package/select-pure)
[](https://www.webcomponents.org/element/select-pure)
## Description
SelectPure is a Web Component (Custom Element) which makes it super easy to use and customize. Main goal is to use extended API of the native HTML `<select>` element and provide additional features, like autocomplete, custom styling and many more. The package itself is stable to be used, however, if you've found any issues, please report them [here](https://github.com/dudyn5ky1/select-pure/issues) or create a PR of your own.
If you want to use older version, please refer to this [README](./README-v1.md).
## Demo
Interactive demo with many examples is available [here](https://www.webcomponents.org/element/select-pure).
## Usage
SelectPure is very easy to use. At first you have to install a package
```bash
yarn add select-pure
```
or
```bash
npm i select-pure --save
```
then include it in your JavaScript file:
```javascript
import 'select-pure';
```
*Important!* If you want to use a minified ES2015 version, include the package as following:
```javascript
import 'select-pure/dist/index.js';
```
Use in the similar way as you would use a native HTML `<select>`.
<!--
```
<custom-element-demo height="280">
<template>
<script src="https://unpkg.com/select-pure@latest/dist/index.js"></script>
<next-code-block></next-code-block>
</template>
</custom-element-demo>
```
-->
```javascript
<select-pure name="country" id="country">
<option-pure value="" disabled hidden>-- Please select a country --</option-pure>
<option-pure value="UA">Ukraine</option-pure>
<option-pure value="PL">Poland</option-pure>
<option-pure value="DE">Germany</option-pure>
<option-pure value="US">USA</option-pure>
<option-pure value="RU" disabled>Russia</option-pure>
</select-pure>
```
## SelectPure instance
In order to call API methods of the `SelectPure`, subscribe to callbacks or use it's properties, you can simple use `querySelector`.
```javascript
const selectPure = document.querySelector("select-pure");
console.log(selectPure.selectedIndex);
selectPure.disable();
```
### Attributes
`<select-pure>` supports the following attributes: `name`, `id`, `multiple`, `default-label` and `disabled`.
`<option-pure>` supports `value`, `label`, `disabled`, `selected` and `hidden` attributes.
### Available properties
| property | description |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| selectedIndex | Returns index of the selected option. You can also manipulate selected value with changing this property (`selectPure.selectedIndex = 2`). Just like in the native `<select>`. |
| value | Returns selected value. |
| selectedOptions | Returns and array of selected `<option>`s. Works only in `multiple` mode. |
| values | Returns and array of selected values. Works only in `multiple` mode. |
### Callbacks
If you want to set a callback for when the new value is selected, you can just use the traditional `addEventListener`.
```javascript
const selectPure = document.querySelector("select-pure");
selectPure.addEventListener("change", (event) => {
// You can use
// event.target.value or
// event.currentTarget.value
});
```
### API methods
| method | description |
|-----------|--------------------|
| disable() | Disables select. |
| enable() | Enables select. |
| open() | Opens a dropdown. |
| close() | Closes a dropdown. |
### Custom styles
SelectPure offers high level of customisation. You can match any design you want by just providing a simple set of css variables. Below you can find their names and default values that are included in the package.
```css
select-pure {
--select-height: 44px;
--select-width: 100%;
--border-radius: 4px;
--border-width: 1px;
--border-color: #000;
--padding: 0 10px;
--dropdown-z-index: 2;
--disabled-background-color: #bdc3c7;
--disabled-color: #ecf0f1;
--background-color: #fff;
--color: #000;
--hover-background-color: #e3e3e3;
--hover-color: #000;
--selected-background-color: #e3e3e3;
--selected-color: #000;
--dropdown-gap: 0;
--font-size: 14px;
--font-family: inherit;
--font-weight: 400;
--select-outline: 2px solid #e3e3e3;
--dropdown-items: 4;
}
```
Example of the custom styles.
<!--
```
<custom-element-demo height="280">
<template>
<script src="https://unpkg.com/select-pure@latest/dist/index.js"></script>
<style>
select-pure.dark {
--select-height: 40px;
--select-width: calc(100% - 20px);
--border-radius: 8px;
--border-width: 2px;
--border-color: #2f3640;
--padding: 0 10px;
--dropdown-z-index: 100;
--disabled-background-color: #636e72;
--disabled-color: #b2bec3;
--background-color: #2f3640;
--color: #fff;
--hover-background-color: #404a55;
--hover-color: #fff;
--selected-background-color: #404a55;
--selected-color: #fff;
--dropdown-gap: 2px;
}
</style>
<next-code-block></next-code-block>
</template>
</custom-element-demo>
```
-->
```javascript
<select-pure name="country" id="country" class="dark">
<option-pure value="" disabled hidden>-- Please select a country --</option-pure>
<option-pure value="UA">Ukraine</option-pure>
<option-pure value="PL">Poland</option-pure>
<option-pure value="DE">Germany</option-pure>
<option-pure value="US">USA</option-pure>
<option-pure value="RU" disabled>Russia</option-pure>
</select-pure>
```
### `<form>` support
If you place `<select-pure>` inside a `<form>` and specify a `name` or `id` attribute, it will then append a hidden `input` with a given name inside a `<form>` and trigger `change` event, when value is selected.
## TODO
- [ ] Autocomplete input
- [ ] Callback for autocomplete input
- [ ] Custom matching/filter pattern
- [ ] Fill README with React/Angular/Vue/Svelte/Purejs examples of usage;
- [ ] Precommit hooks;
- [ ] Add destroy method;
- [ ] Make sure Select behaves correctly when attributes are changed or options are removed from the DOM (MutationObserver);
- [ ] Sometimes one select scrolls dropdown in the others?
- [ ] Support keyboard arrows;
2.1
- [ ] Option groups;
- [ ] Required attribute support
- [ ] Contribution guide;
- [ ] Position of the dropdown;
## License
```MIT```