Custom Select

Custom Select is a lightweight, dependency-free JavaScript library that transforms native HTML <select> elements into fully styleable custom dropdowns while keeping the underlying native select in the DOM for value and form sync.

What is Custom Select?

Custom Select is an open-source browser library (published on npm as custom-select) that takes native <select> elements as input and produces a configurable custom dropdown UI — a container div, a span opener, a panel div, and option divs — while preserving the native select's value, disabled state, and change events. It accepts a CSS selector, an HTMLElement, or a list of elements (NodeList, HTMLCollection, or Array) and returns an array of instances with methods and properties for full programmatic control. The project is maintained on GitHub with 100 stars and includes demos hosted on CodeSandbox.

Key Features

• Zero dependencies — the core library needs no jQuery or other frameworks; it works with ES6 modules, CommonJS (require('custom-select').default), or a plain <script> tag.
• Configurable CSS classes — all structural and state classes (containerClass, openerClass, panelClass, optionClass, optgroupClass, isSelectedClass, hasFocusClass, isDisabledClass, isOpenClass) can be renamed through pluginOptions, leaving no styling locked in.
• Full instance API — properties open, disabled, and value read and set state on both the custom UI and the native select; methods append, insertBefore, remove, empty, and destroy manage options and optgroups at runtime.
• Custom events — the container dispatches custom-select:open, custom-select:close, custom-select:disabled, custom-select:enabled, and custom-select:focus-outside-panel, while the native select still fires its standard change event.
• jQuery adaptor — an alternate build in the release downloads lets jQuery projects call $('#mySelect').customSelect() and access the same features through string commands.
• Broad browser support — the documentation lists Chrome, Safari 7.0, Firefox 10, Android 4.0, Mobile Safari 6.0, and Internet Explorer 10.
• Example demos — CodeSandbox examples cover Base, Bootstrap, Control buttons, GSAP animations, jQuery usage, and Mobile Touch Devices.

Who is it for?

• Front-end developers building custom form controls need a small drop-in for native selects that keeps keyboard navigation, focus states, and form submission behavior.
• UI library maintainers looking for a standards-based select replacement without pulling a full framework can use Custom Select as a standalone component inside their design systems.
• Teams stuck on older browsers — with support back to IE10 and Android 4.0, the library fits projects with conservative browser requirements.
• jQuery-based applications can use the dedicated adaptor to upgrade selects without rewriting their existing jQuery patterns.

What can you do with Custom Select?

• Brand-styled forms: replace every default-looking dropdown with a custom UI that matches your site's CSS, because all structural classes are configurable and the included default stylesheet is fully optional.
• Dynamic option editing: use append, insertBefore, remove, and empty to add or delete options and optgroups after initialization, and the custom panel updates automatically to mirror the native select.
• Custom open/close animations: listen for custom-select:open and custom-select:close events on the container, or intercept custom-select:focus-outside-panel to animate scrolling instead of the default jump.
• Touch-device fallback: follow the Mobile Touch Devices demo to show the native select on mobile while keeping the custom UI on desktop.

How does it work?

Calling customSelect('select') wraps each matching native <select> in the generated container/opener/panel markup, then rebuilds the panel options from the native <option> and <optgroup> elements. The returned array holds instance objects; setting value, open, or disabled on an instance synchronously updates both the custom UI and the hidden native select, which keeps form behavior intact.

Pros and cons

• Pros: zero runtime dependencies; small, focused API; fully customizable class names; includes a jQuery adaptor; works on IE10 and old Android.
• Cons: the default appearance is minimal, so production use generally requires writing your own CSS; CommonJS consumers must remember the .default suffix when requiring the package.

FAQ

How do I install Custom Select?

Run npm install --save custom-select, or download the minified build from the GitHub releases page. For ES6 use import customSelect from 'custom-select'; for CommonJS use var customSelect = require('custom-select').default.

Does Custom Select require jQuery?

No. The core custom-select package has zero dependencies. A separate jQuery-adapted build is available in the release downloads for projects that prefer the $('#mySelect').customSelect() syntax.

How can I restyle the dropdown?

Every class name in the generated markup is configurable through the pluginOptions object, so you can supply your own class names and write completely custom CSS. A basic custom-select.css file is included in releases as a starting point.

Which browsers are supported?

Chrome, Safari 7.0, Firefox 10, Android 4.0, Mobile Safari 6.0, and Internet Explorer 10 are the supported browsers listed in the project docs.

How do I get a plugin instance after initialization?

The init call returns an array of instances, so use customSelect('select')[0]. You can also read the customSelect property on the native select element or on the generated container div (for example, document.querySelector('select').customSelect).