Accessible custom dropdown web component.
npm install @magic-spells/dropdown-selectA fully accessible custom dropdown web component that can be used as a replacement for the native element with enhanced styling options and keyboard navigation.
š Live Demo - See it in action!
- šØ Fully customizable styling
- āæ WAI-ARIA compliant for accessibility
- āØļø Complete keyboard navigation support
- š± Mobile-friendly
- š Typeahead search functionality
- š Auto-scroll to selected items in long lists
- š§© Zero dependencies
- š¦ Small footprint (~3KB minified and gzipped)
``bash`
npm install @magic-spells/dropdown-select
`html`
rel="stylesheet"
href="https://unpkg.com/@magic-spells/dropdown-select/dist/dropdown-select.min.css"
/>
This package provides multiple distribution formats for different environments:
- ES Module: dropdown-select.esm.js`
javascript`
import { DropdownSelect } from '@magic-spells/dropdown-select';
- CommonJS: dropdown-select.cjs.js`
javascript`
const { DropdownSelect } = require('@magic-spells/dropdown-select');
- UMD: dropdown-select.js and dropdown-select.min.js`
- Works in browsers via script tag
- Compatible with AMD loaders (RequireJS)
- Works in Node.js
html`
`html
Select an option
`
The dropdown automatically detects if there's enough space below and will open upward if needed. You can explicitly set the direction with the position attribute:
`html
`
The selected value is stored in the hidden input element. You can also listen for the change event:
`javascript`
document
.querySelector("dropdown-select")
.addEventListener("change", function (e) {
console.log("Selected value:", e.detail.value);
console.log("Selected text:", e.detail.text);
});
| Key | Action |
| ------------- | ---------------------------------------------- |
| Tab | Focus the dropdown trigger |
| Enter / Space | Open the dropdown or select the focused option |
| Escape | Close the dropdown without selecting |
| Arrow Down | Move to the next option |
| Arrow Up | Move to the previous option |
| Home | Jump to the first option |
| End | Jump to the last option |
| Any letter | Jump to an option starting with that letter |
The component comes with default styling, but you can customize it by overriding the CSS variables or using your own CSS.
This package provides multiple ways to integrate with your SCSS workflow:
`scss
// Option 1: Use the main entry point (recommended)
@use "@magic-spells/dropdown-select/scss" with (
$color-primary: #ff5722,
$border-radius: 0.5rem
);
// Option 2: Import individual files
@use "@magic-spells/dropdown-select/scss/variables" with (
$color-primary: #ff5722,
$border-radius: 0.5rem
);
@use "@magic-spells/dropdown-select/scss/dropdown-select";
// Option 3: Direct paths (if needed)
@use "node_modules/@magic-spells/dropdown-select/dist/dropdown-select.scss";
@use "node_modules/@magic-spells/dropdown-select/dist/scss/dropdown-select";
`
You can customize the dropdown appearance using CSS custom properties. All styling aspects are available as variables:
`css`
dropdown-select {
/ Sizing /
--select-dropdown-width: 400px;
--select-options-max-height: 15rem;
--select-caret-size: 0.25rem;
/ Colors /
--select-color-text: #333;
--select-color-background: #fff;
--select-color-border: #ddd;
--select-color-border-hover: #aaa;
--select-color-border-dark: #666;
--select-color-primary: #ff5722;
--select-color-primary-rgb: 255, 87, 34; / For alpha transparency /
--select-color-hover: #f5f5f5;
--select-color-focus: #e6f7ff;
--select-color-selected: #ffede6;
/ Spacing /
--select-spacing-xs: 0.25rem;
--select-spacing-sm: 0.75rem;
--select-spacing-md: 1rem;
/ Misc /
--select-border-radius: 0.5rem;
--select-box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
--select-z-index-dropdown: 10;
--select-transition-duration: 0.2s;
}
This enables theme switching and custom styling without modifying the component itself.
`html
Apple
type="hidden"
class="dropdown-hidden-input"
name="selected-fruit"
value="apple"
/>
`
`html
`
- change - Fired when an option is selecteddetail.value
- - The value of the selected optiondetail.text
- - The text content of the selected option
- show() - Opens the dropdownhide()
- - Closes the dropdowntoggleDropdown()
- - Toggles the dropdown open/closedselectOption(event)` - Selects an option and updates the value
-
The component works in all modern browsers that support Custom Elements v1.
MIT