Skip to content

andrewvasilchuk/vue-accessible-select

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

34 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

vue-accessible-select

Vue.js accessible select component made according to WAI-ARIA practices.

✨ Features

  • fully accessible;
  • ⌨️ keyboard navigation (Page Up/Down, Home, End, Esc);
  • πŸ”£ type-ahead to select option that starts with typed symbols;
  • πŸ’… style agnostic, so you can style it whatever you like (but including core.scss is highly encouraged).

Demo

Edit vue-accessible-select

πŸ’Ώ Installation

πŸ“¦ Via NPM

$ npm install vue-accessible-select --save

🧢 Via Yarn

$ yarn add vue-accessible-select

Initialization

As a plugin

It must be called before new Vue().

import Vue from 'vue'
import VueAccessibleSelect from 'vue-accessible-select'

Vue.use(VueAccessibleSelect)

As a global component

import Vue from 'vue'
import { VueAccessibleSelect } from 'vue-accessible-select'

Vue.component('VueAccessibleSelect', VueAccessibleSelect)

As a local component

import { VueAccessibleSelect } from 'vue-accessible-select'

export default {
  name: 'YourAwesomeComponent',
  components: {
    VueAccessibleSelect,
  },
}

ℹ️ Note to set global options (for example transition for each select component), you should do the following:

import { config } from 'vue-accessible-select'

config.transition = {
  name: 'foo',
}

⚠️ Options passed locally via props will always take precedence over global config options.

Default config.js:

export default {
  transition: null,
}

πŸš€ Usage

Template

<template>
  <vue-accessible-select
    v-model="value"
    :options="options"
    :transition="{ name: 'foo' }"
    label="foo"
    placeholder="bar"
    disabled
  ></vue-accessible-select>
</template>

Script

export default {
  // ...
  data() {
    return {
      value: undefined,
      options: [
        {
          value: 0,
          label: 'πŸ‡ Grape',
        },
        {
          value: { foo: 'bar' },
          label: 'πŸ‰ Watermelon',
        },
        {
          value: { foo: 'bar' },
          label: 'πŸ₯ Kiwi',
        },
        {
          value: false,
          label: 'πŸ₯­ Mango',
        },
        {
          value: true,
          label: 'πŸ“ Strawberry',
        },
        {
          value: 'lemon',
          label: 'πŸ‹ Lemon',
        },
      ],
    }
  },
  // ...
}

🎨 Styles

Then don't forget to include core styles. Also library is sipped with default theme styles you can use.

SASS:

// recommended
@import 'vue-accessible-select/src/styles/core.scss';

// optional
@import 'vue-accessible-select/src/styles/themes/default.scss';

Or already compiled CSS:

/* recommended */
@import 'vue-accessible-select/dist/styles/core.scss';

/* optional */
@import 'vue-accessible-select/dist/styles/themes/default.scss';

⚠️ Note that when you import already compiled CSS you don't have ability to override SASS variables during build process, so it is preferable to use .scss file.

When importing core.scss, there are SASS variables you can override during build process:

$v-select-menu-position-top: 100% !default;
$v-select-arrow-size: 8px !default;

API

βš™οΈ Props

<vue-accessible-select> accepts some props:

Prop Description
options: array required Array of select options. Should be an array of objects that match the following pattern { value: any, label: string }
value: any required Current value of select. When value is undefined, it is considered that select has no current value.
label: string Select label
placeholder: string Select placeholder
disabled: boolean Whether select is disabled
transition: object Through this object you can configure the transition of .v-select__menu entrance and leave. Should match the following pattern { name: string, mode: string? }

πŸ•³οΈ Slots

<vue-accessible-select> provides you with some slots and scopedSlots you can use to fit your needs.

Slot Scope Description
label Label slot
prepend Prepend slot
placeholder { placeholder } Placeholder slot
selected { value, option } Selected slot
arrow Arrow slot
option { value, option } Option slot
no-options No options slot

Example of possible usage of slots and scopedSlots

<vue-accessible-select>
  <template v-slot:label>
    <strong>πŸ˜‹ Just a label slot:</strong>
  </template>
  <template v-slot:prepend>
    <svg viewBox="0 0 54 54">
      <path d="M27 1l8 17 19 3-14 13 4 19-17-9-17 9 3-19L0 21l19-3z" />
    </svg>
  </template>
  <template v-slot:placeholder
    >πŸŽƒ I am a placeholder slot</template
  >
  <template v-slot:selected="{ value, option }"
    >πŸ”₯ Woooow, {{ option.label }}</template
  >
  <template v-slot:option="{ value, option }"
    >Option: {{ option.label }}</template
  >
  <template v-slot:no-options
    >Keine Optionen</template
  >
</vue-accessible-select>

⌨️ Keyboard shortcuts

<vue-accessisble-select> is fully accessible when it comes to keyboard interaction.

Here is some useful keys and their appropriate actions:

  • Down Arrow – Moves focus and selection to the next option.
  • Up Arrow – Moves focus and selection to the previous option.
  • Home – Moves focus and selection to the first option.
  • End – Moves focus and selection to the last option.
  • Esc – Closes menu.

Type ahead:

  • Type a character: focus and selection moves to the next option with a label that starts with the typed character;
  • Type multiple characters in rapid succession: focus and selection moves to the next option with a label that starts with the string of characters typed.

Powered by

  • Rollup (and plugins);
  • SASS and node-sass;
  • PostCSS;
  • Autoprefixer.

πŸ”’ License

MIT