Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/invisiburu/vue-picker
A native-like select field, but better
https://github.com/invisiburu/vue-picker
picker vue vuejs2 vuejs3
Last synced: 2 days ago
JSON representation
A native-like select field, but better
- Host: GitHub
- URL: https://github.com/invisiburu/vue-picker
- Owner: invisiburu
- License: mit
- Created: 2020-08-01T22:16:51.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-05T10:08:07.000Z (over 1 year ago)
- Last Synced: 2024-09-21T15:47:55.243Z (6 days ago)
- Topics: picker, vue, vuejs2, vuejs3
- Language: Vue
- Homepage:
- Size: 4.77 MB
- Stars: 18
- Watchers: 1
- Forks: 4
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# vue-picker
A native-like select field, but better.
Mostly behaves like native `` but accepts custom markup for the options
and the opener button.
The options are navigatable from the keyboard. The opener text is easily
customizable.
The package versions of 2 and higher work with Vue3. For Vue2, use prior
versions of the package.
## Demo
See the demo: https://invisiburu.github.io/vue-picker/
See the demo sources in [demo/](demo/)
## The Problem
When you think about a custom selector, you usually come to provide the
options as an array. For sure, it resolves some reactivity issues by default
but also has some pitfalls.
One such pitfall that in most cases, you need to map your data list to an
array of something like `{ label, value }` thus spending extra resources.
Additionally, you write dummy code to display an options selector.
The second pitfall is that default `` provides a more natural way
to render lists - just by giving the elements by themselves, not the arrays.
The third pitfall is the poor customization capabilities of the options.
Which mostly looks similar to the problem of default ``
but a bit milder.
`VuePicker` resolves all of these issues.
## TypeScript
Currently, `VuePicker` comes with no TS declarations because of the poor TS
support within Vue infrastructure. Please contact me or craft an issue if you
think the times have changed or you have any other arguments of introducing
TypeScript to the package. Also, you're welcome to contribute.
## Installation
### Using unpkg:
```html
const App = {
template:
'<div>' +
'<h3>Hello world</h3>' +
'<VuePicker v-model="mv">' +
'<VuePickerOption value="opt0">Option 0</VuePickerOption>' +
'<VuePickerOption value="opt1">Option 1</VuePickerOption>' +
'</VuePicker>' +
'</div>',
data: function () { return { mv: 'opt1' } },
}
const app = Vue.createApp(App)
app.use(window.VuePicker)
app.mount('#app')
```
### Using npm:
```bash
npm i --save @invisiburu/vue-picker
```
Import in your project:
```js
import { VuePicker, VuePickerOption } from '@invisiburu/vue-picker'
// optional css
import '@invisiburu/vue-picker/dist/vue-picker.min.css'
const app = createApp(/* ... */)
app.component('VuePicker', VuePicker)
app.component('VuePickerOption', VuePickerOption)
```
## Usage
### Basic:
```html
Empty
Red
Green
Blue
Yellow
How about teal (Teal will be shown instead)
```
### Custom options:
```html
Some italics or bold?
Or something more special?
I am a subheading!
.grid {
display: grid;
grid: auto-flow auto / auto;
gap: 4px;
}
.title {
font-size: 1.05em;
font-weight: bold;
}
.subtitle {
font-size: 0.9em;
color: lightgray;
}
```
### Custom opener:
```html
{{ opener.value }}
{{ opener.text }}
Value 1
Value 2
```
## Api
### `VuePicker`
#### Props:
- `modelValue` - the value, should be a string. The behaviour is not defined for
values that do not exist within provided options.
- `placeholder` - a text to show when `value` is null, undefined or an
empty string.
- `isAutofocus` - focus the opener on mount.
- `isDisabled` - disable the component.
- `onKeyDown` - accepts a function to run before the default key-down listener.
Please see the [onKeyDown()](#onkeydown-prop) section for more details
#### Emitted events:
- `input` - an option selected. Carries the new value to assign.
- `open` - dropdown open.
- `close` - dropdown closed. Carries `true` if closed by the outer click.
#### Slots:
- `default` - a picker option. Should be a ``.
- `opener` - override the displayed opener text.
Provides the `opener` scope var with `{ value, text, opt }`, where:
- `value` - the selected value.
- `text` - the text that was intended to display by the opener
(HTML stripped). Content of the `placeholder` attribute prevails over
empty option values.
- `opt` - context of the current option.
- `openerIco` - override the default expand arrow
- `dropdownInner` - use if you want a custom dropdown inner container
### `VuePickerOption`
#### Props:
- `isDisabled` - disable the option. Disabled options cannot be picked or
navigated.
- `value` - value to set on when the option selected.
- `text` - text to be displayed instead of the content of the `default` slot.
Also overrides the `optHtml` and `optTxt` computed properties of the
component.
#### Slots:
- `default` - content to be displayed in the options list and in the opener
when the option is selected. Can contain any markup, the opener will
display it as is. Please consider using the `text` prop if you plan complex
things in here.
#### Computed
You can use these computed properties within the `opt` param of the `opener`
slot.
- `optHtml` - returns the HTML from the `default` slot of the component.
- `optTxt` - returns the HTML from the `default` slot of the component.
Mostly the same as `text` param of the `opener` slot but does not respect
`placeholder` attr of the picker.
### `onKeyDown prop`
Accepts a function like the following:
```ts
function onKeyDown (event: KeyboardEvent, dropdown: any, options: any) => boolean
```
The listener is fired in two cases:
1. When the dropdown in open
2. When the dropdown is closed but the opener is focused
Return `false` from your `onKeyDown()` function to prevent the default
key-down handler.
## Issues
In case of a bug or a suggestion, please report on the [Issues page](https://github.com/invisiburu/vue-picker/issues)
or contact me by email.
## Changelog
Check the changes in [CHANGELOG.md](CHANGELOG.md)
## TODO
- TS definitions
- Better onKeyDown description
- Unit tests
- Search
- Handle keys: Page down, Page up
- Animation support
- Dropdown position switch if does not fit the screen
- Outer label[for=""] support
- Readonly attr - ?
- iOS, Android full screen style - ?
## License
MIT