or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-usage.mddata-management.mdevents.mdindex.mdtemplates.mdtypes.md
tile.json

tessl/npm-choices--js

A vanilla JS customisable text input/select box plugin

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/choices.js@10.2.x

To install, run

npx @tessl/cli install tessl/npm-choices--js@10.2.0

index.mddocs/

Choices.js - Customizable Select Boxes and Text Inputs

Choices.js is a lightweight, vanilla JavaScript library for creating customizable select boxes and text inputs with search, filtering, and multi-selection capabilities. This comprehensive documentation covers all aspects of the library for AI agents and developers.

Package Information

  • Package Name: Choices.js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install choices.js

Installation

npm install choices.js
yarn add choices.js

Core Imports

ESM (ES Modules)

import Choices from 'choices.js';
import { 
  DEFAULT_CONFIG, 
  DEFAULT_CLASSNAMES,
  EVENTS,
  KEY_CODES,
  templates
} from 'choices.js';

CommonJS

const Choices = require('choices.js');
const { 
  DEFAULT_CONFIG, 
  DEFAULT_CLASSNAMES,
  EVENTS,
  KEY_CODES,
  templates
} = require('choices.js');

Browser (UMD)

<script src="path/to/choices.js"></script>
<script>
  const choices = new Choices('#my-select');
</script>

Basic Usage Examples

Single Select Enhancement

// Transform a basic select element
const element = document.querySelector('#my-select');
const choices = new Choices(element, {
  searchEnabled: true,
  placeholder: true,
  placeholderValue: 'Choose an option...'
});

Multi-Select with Custom Options

const multiSelect = new Choices('#multi-select', {
  removeItemButton: true,
  maxItemCount: 5,
  searchResultLimit: 4,
  renderSelectedChoices: 'always'
});

Text Input with Autocomplete

const textInput = new Choices('#text-input', {
  delimiter: ',',
  editItems: true,
  maxItemCount: -1,
  removeItemButton: true
});

Dynamic Choice Management

const choices = new Choices('#dynamic-select');

// Set choices programmatically
choices.setChoices([
  { value: 'choice1', label: 'Choice 1', selected: true },
  { value: 'choice2', label: 'Choice 2', disabled: false },
  { value: 'choice3', label: 'Choice 3', customProperties: { description: 'Custom data' } }
], 'value', 'label', true);

// Listen for changes
element.addEventListener('change', (event) => {
  console.log('Selection changed:', event.detail);
});

Architecture Overview

Choices.js follows a component-based architecture with several key systems:

Core Components

  • Choices Class: Main controller managing lifecycle and coordination
  • Store: Redux-based state management for choices, items, and groups
  • Templates: Modular HTML generation system
  • Event System: Custom event emission and handling

Component Hierarchy

Choices Instance
├── PassedElement (original input/select)
├── ContainerOuter (main wrapper)
│   ├── ContainerInner (inner wrapper)
│   │   ├── ItemList (selected items)
│   │   └── Input (search/input field)
│   └── Dropdown (choice list container)
│       └── ChoiceList (available options)

Data Flow

  1. Initialization: DOM elements wrapped, configuration merged
  2. State Management: All interactions update central Redux store
  3. Rendering: Template functions generate HTML from state
  4. Events: Custom events emitted for external integration

Key Capabilities

Core Usage Patterns

The main Choices class provides comprehensive control over select elements and text inputs. Essential methods include initialization, value management, and lifecycle control.

const choices = new Choices(element, config);
choices.init();                    // Initialize component
choices.setValue(['value1']);      // Set selected values
choices.getValue();                // Get current values
choices.destroy();                 // Clean up instance

→ See Core Usage for complete API reference

Configuration System

Over 45 configuration options control every aspect of behavior, appearance, and functionality.

{ .api }
interface Options {
  // Behavioral options
  searchEnabled: boolean;
  removeItemButton: boolean;
  editItems: boolean;
  maxItemCount: number;
  
  // Display options
  allowHTML: boolean;
  placeholder: boolean;
  placeholderValue: string;
  
  // Advanced options
  fuseOptions: object;
  callbackOnInit: Function;
  // ... 40+ more options
}

→ See Configuration for all options and defaults

Data Management

Comprehensive APIs for managing choices, selected items, and values with full programmatic control.

// Choice management
choices.setChoices(choicesArray, 'value', 'label', replaceChoices);
choices.clearChoices();

// Item management  
choices.setChoiceByValue('specific-value');
choices.removeActiveItemsByValue('remove-value');
choices.highlightItem(item, runEvent);

→ See Data Management for complete data APIs

Event System

Rich event system with 9 event types for monitoring user interactions and state changes.

{ .api }
type EventType = 
  | 'addItem' 
  | 'removeItem' 
  | 'highlightItem' 
  | 'unhighlightItem'
  | 'choice' 
  | 'change' 
  | 'search' 
  | 'showDropdown' 
  | 'hideDropdown'
  | 'highlightChoice';

→ See Events for event handling and details

Template Customization

Modular template system with 12 template functions for complete UI customization.

{ .api }
interface Templates {
  containerOuter: Function;
  containerInner: Function;
  itemList: Function;
  placeholder: Function;
  item: Function;
  choiceList: Function;
  choiceGroup: Function;
  choice: Function;
  input: Function;
  dropdown: Function;
  notice: Function;
  option: Function;
}

→ See Templates for customization guide

Type System

Comprehensive TypeScript support with interfaces for all data structures and configuration.

{ .api }
interface Choice {
  id: number;
  label: string;
  value: string;
  selected: boolean;
  disabled: boolean;
  customProperties?: Record<string, any>;
}

interface Item extends Choice {
  choiceId: number;
  highlighted: boolean;
}

→ See Types for complete type definitions

Quick Start Workflow

  1. Install: npm install choices.js
  2. Import: import Choices from 'choices.js';
  3. Initialize: const choices = new Choices('#my-select', options);
  4. Configure: Set options for behavior and appearance
  5. Handle Events: Listen for change, addItem, removeItem events
  6. Manage Data: Use setChoices(), setValue(), getValue() methods
  7. Customize: Override templates and styles as needed

Browser Compatibility

  • Chrome/Edge: Latest 2 versions
  • Firefox: Latest 2 versions
  • Safari: Latest 2 versions
  • IE11: Supported with polyfills

Dependencies

  • deepmerge: Configuration object merging
  • fuse.js: Fuzzy search functionality
  • redux: Internal state management

This documentation provides complete coverage of Choices.js v10.2.0 for effective library usage without requiring access to source code.