pickle-select
v1.2.0
Published
A modular, accessible vanilla JS <select> replacement utility with a funny name.
Maintainers
Readme
Pickle 🥒
A lightweight, dependency-free, and fully accessible custom select component with a funny name.
Why Pickle?
Native <select> elements are about as customizable as a brick wall and twice as frustrating. After years of wrestling with select styling and accessibility, I built Pickle to be the select component I always wanted to use.
Features
- Featherlight: Zero dependencies, minimal footprint (~26KB minified, ~6KB gzipped)
- Accessible by default: Full WAI-ARIA support, keyboard navigation, screen reader friendly
- Future-proof: Rich programmatic API built for today's humans and tomorrow's cyborgs
- Highly themeable: CSS custom properties with 6 included themes
- Smart search: Built-in filtering with fuzzy search support
- Touch-friendly: Optimized for mobile and touch devices
- Performance-focused: Virtual scrolling handles thousands of options smoothly
- Secure: Built-in XSS protection and input sanitization
- Multi-select: Single and multiple selection modes
- Rich API: Comprehensive methods for dynamic manipulation
Accessibility
Pickle is built with accessibility as a first-class citizen:
- Keyboard Navigation: Full arrow key, Enter, Escape, Home/End support
- Screen Reader Support: Proper ARIA labels, roles, and live regions
- Focus Management: Logical focus flow and visual indicators
- High Contrast: Works with Windows High Contrast mode
- Touch Support: Optimized for touch devices and screen readers
WCAG Compliance
- WCAG 2.1 AA compliant out of the box
- Proper color contrast ratios
- Keyboard-only operation support
- Screen reader announcements for state changes
Documentation
Full documentation is available at picklejs.dev/docs.
Quick Start
Installation
npm install pickle-selectOr use a CDN:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.min.css">
<!-- UMD Version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.umd.min.js"></script>
<script>
const pickle = new Pickle('#my-select', { debug: true });
</script>
<!-- ESM Version -->
<script type="module">
import Pickle from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.esm.min.js';
const pickle = new Pickle('#my-select', { debug: true });
</script>Available from CDN:
- https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.esm.min.js
- https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.umd.min.js
- https://cdn.jsdelivr.net/npm/[email protected]/dist/pickle.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/material/material.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/brutalist/brutalist.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/minimalist/mnml.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/neumorphic/neumorphic.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/skeuomorphic/skeuomorphic.min.css
- https://cdn.jsdelivr.net/npm/[email protected]/dist/theme/glassmorphic/glassmorphic.min.css
Building and Development
# Clone the repository
git clone https://github.com/yannickoo/pickle.git
cd pickle
# Install dependencies
npm install
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverageContributing
I'd love your help making Pickle better! Please follow these guidelines:
Development Setup
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/pickle.git cd pickle - Install dependencies:
npm install - Create a feature branch:
git checkout -b feature/your-feature-name # or git checkout -b fix/issue-description
Making Changes
Make your changes with these guidelines:
- Follow existing code style and patterns
- Add tests for new functionality
- Update documentation if needed
- Do not include the dist/ directory in your pull request. I manually build and commit the production files when a new version is released.
Test your changes:
npm test # Run all tests npm run test:watch # Run tests in watch mode npm run test:coverage # Check coverageEnsure quality:
- All tests must pass
- Maintain or improve test coverage
- No console errors or warnings
Submitting
Commit with clear messages:
git commit -m "feat: add fuzzy search support" git commit -m "fix: handle empty option values" git commit -m "docs: update API examples"Push and create a Pull Request:
git push origin feature/your-feature-name
Before You Start
- Check existing issues and PRs
- For major changes, please open an issue first to discuss
- Questions? Feel free to ask in an issue!
License
Pickle is released under the Mozilla Public License 2.0.
