Package Exports

@magnit-ce/selectable-items
@magnit-ce/selectable-items/dist/selectable-items.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@magnit-ce/selectable-items) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

magnitce-selectable-items

A custom HTMLElement that makes all of its child elements selectable by clicking on them.

Package size: ~3kb minified, ~4kb verbose.

Quick Reference

<script type="module" src="/path/to/selectable-items[.min].js"></script>

Demos

https://catapart.github.io/magnitce-selectable-items/demo/

Support

Firefox
Chrome
Edge
~~Safari~~ (Has not been tested; should be supported, based on custom element support)

Getting Started

Install/Reference the library

Reference/Install

HTML Import (not required for vanilla js/ts; alternative to import statement)

<script type="module" src="/path/to/selectable-items[.min].js"></script>

npm

npm install @magnit-ce/selectable-items

Import

Vanilla js/ts

import "/path/to/selectable-items[.min].js"; // if you didn't reference from a <script>, reference with an import like this

import { SelectableItemsElement } from "/path/to/selectable-items[.min].js";

npm

import "@magnit-ce/selectable-items"; // if you didn't reference from a <script>, reference with an import like this

import { SelectableItemsElement } from "@magnit-ce/selectable-items";

Overview

The <selectable-items> element is a container element that provides select functionality for all of its child element.

Selection can be done either by pointer events (clicking, tapping, etc), or by key events (tab/shift+tab).

Attributes

The <selectable-items> element uses the following attributes:

|Slot Name|Description |-|-|-| |multi||

`selected()`

The <selectable-items> element provides a selected() function which returns all of the child elements that are currently selected in an Array.

Events

The <selectable-items> element dispatches a change event whenever its selected items become selected or unselected.

Properties

The <selectable-items> element exposes the following properties on the javascript object:

Slot Name	Description	Default Value
`multipleModifierKeys`	A `static` property that defines the `string` values that will match a `KeyEvent`'s `code` property for allowing multiple selections. If a key's `code` is a string in this array, then when that key is held down, the selection will not de-select previous selections. (must also have the `mutli` attribute set to `true`)	`["ShiftLeft", "ShiftRight", "ControlLeft", "ControlRight"]`
`selectKeys`	A `static` property that defines the `string` values that will match a `KeyEvent`'s `code` property for invoking a selection on the currently focused item. If a key's `code` is a string in this array, then when that key is pressed while a child element has focus, that child element will be selected.	`["Enter", "Space"]`
`selectedClassName`	A `static` property that defines the `string` value of the class that will be applied to selected items. When an item is "selected" it will be assigned a class with this property's value.	`selected`

Slots

The <selectable-items> element exposes the following slots:

Slot Name	Description	Default
[Default]	Slot that holds all of the `<selectable-items>`'s children. (note: this slot has no name; all children of the `<selectable-items>` element will be placed in this default slot.)	[empty]

Styling

The <selectable-items> element can be styled with CSS, normally. The <selectable-items> element does not utilize the shadowDOM for layout, so all styling can be done with standard CSS selectors. For its children, they can be styled with standard CSS selectors, as well.

Selected children are have the selected class applied, and their aria-selected attribute set to option. These defaults can be prevented by using the preventDefault function on the <selectable-items>'s change event. The specific class name applied can be changed by using the selectedClassName property of the element.

License

This library is in the public domain. You do not need permission, nor do you need to provide attribution, in order to use, modify, reproduce, publish, or sell it or any works using it or derived from it.