Nunjucks Powers Mozilla

    vue-accessible-multiselect

    0.1.1 • Public • Published

    vue-accessible-multiselect

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

    Table of contents

    Features

    • ♿️ fully accessible to screen readers;
    • ⌨️ supports keyboard navigation (there really a lot of keyboard shortcuts);
    • 🔣 type-ahead to focus 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-multiselect

    Installation

    Via NPM

    $ npm install vue-accessible-multiselect --save

    Via Yarn

    $ yarn add vue-accessible-multiselect

    Initialization

    As a plugin

    It must be called before new Vue().

    import Vue from 'vue'
    import VueAccessibleMultiselect from 'vue-accessible-multiselect'
     
    Vue.use(VueAccessibleMultiselect)

    As a global component

    import Vue from 'vue'
    import { VueAccessibleMultiselect } from 'vue-accessible-multiselect'
     
    Vue.component('VueAccessibleMultiselect', VueAccessibleMultiselect)

    As a local component

    import { VueAccessibleMultiselect } from 'vue-accessible-multiselect'
     
    export default {
      name: 'YourAwesomeComponent',
      components: {
        VueAccessibleMultiselect,
      },
    }

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

    import { config } from 'vue-accessible-multiselect'
     
    config.transition = {
      name: 'foo',
    }

    ⚠️ Note! 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-multiselect
        v-model="value"
        :options="options"
        :transition="{ name: 'foo' }"
        label="foo"
        placeholder="bar"
        disabled
      ></vue-accessible-multiselect>
    </template>

    Script

    export default {
      // ...
      data() {
        return {
          value: [],
          options: [
            {
              value: 0,
              label: '🍇 Grape',
            },
            {
              value: { foo: 'bar' },
              label: '🍉 Watermelon',
            },
            {
              value: [1, 2, 3],
              label: '🥝 Kiwi',
            },
            {
              value: false,
              label: '🥭 Mango',
            },
            {
              value: true,
              label: '🍓 Strawberry',
            },
            {
              value: 'lemon',
              label: '🍋 Lemon',
            },
          ],
        }
      },
      // ...
    }

    Styles

    After that don't forget to include core styles. Note that library is sipped with default theme styles you can use.

    SASS:

    // recommended 
    @import 'vue-accessible-multiselect/src/styles/core.scss';
     
    // optional 
    @import 'vue-accessible-multiselect/src/styles/themes/default.scss';

    Or already compiled CSS:

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

    ⚠️ Note! 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.

    core.scss, contains some SASS variables you can override during build process:

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

    /themes/default.scss SASS variables are listed here.

    API

    Props

    <vue-accessible-multiselect> accepts some props:

    Prop Description
    options: array required. Array of multiselect options. Should be an array of objects that match the following pattern { value: any, label: string }
    value: array required. Current value of multiselect.
    label: string Multiselect label
    placeholder: string Multiselect placeholder
    disabled: boolean Whether multiselect is disabled
    transition: object Through this object you can configure the transition of .v-multiselect__menu entrance and leave. Should match the following pattern { name: string, mode: string? }

    Slots

    <vue-accessible-multiselect> 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, options } 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-multiselect>
      <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:label
        >😋 Select one of the following options:</template
      >
      <template v-slot:placeholder
        >🎃 Select one of the following options</template
      >
      <template v-slot:arrow>💎</template>
      <template v-slot:selected="{ value, options }">🔥 Woooow, {{ value }}</template>
      <template v-slot:option="{ option }"
        >{{ option.label }}</template
      >
    </vue-accessible-multiselect>

    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 to the next option
    • Up Arrow Moves focus to the previous option
    • Home Moves focus to first option
    • End Moves focus to last option
    • Space Changes the selection state of the focused option
    • Shift + Down Arrow Moves focus to and toggles the selected state of the next option
    • Shift + Up Arrow Moves focus to and toggles the selected state of the previous option
    • Shift + Space Selects contiguous items from the most recently selected item to the focused item
    • Control + Shift + Home Selects the focused option and all options up to the first option. Moves focus to the first option.
    • Control + Shift + End Selects the focused option and all options down to the last option. Moves focus to the last option
    • Control + A Selects all options in the list. If all options are selected, unselects all options

    Type ahead:

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

    Tests

    Unit

    Jest and VueTestUtils is used for unit tests.

    You can run unit tests by running next command:

    npm run test:unit

    Development

    1. Clone this repository
    2. Install dependencies using yarn install or npm install
    3. Start development server using npm run dev

    Build

    1. To build production ready build simply run npm run build:

    After successful build the following dist folder will be generated:

    ├── styles
    │   ├── themes
    │   │   ├── default.css
    │   ├── core.css
    ├── vue-accessible-multiselect.common.js
    ├── vue-accessible-multiselect.esm.js
    ├── vue-accessible-multiselect.js
    ├── vue-accessible-multiselect.min.js
    

    Powered by

    • Rollup (and plugins)
    • Babel
    • SASS and node-sass
    • PostCSS
    • Autoprefixer
    • Jest
    • Vue Test Utils
    • keycode-js
    • lodash

    License

    MIT

    Install

    npm i vue-accessible-multiselect

    DownloadsWeekly Downloads

    215

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    124 kB

    Total Files

    18

    Last publish

    Collaborators

    • 3vil_arthas