Chipster

Chipster is a composable and flexible multi-entry input component for React. Perfect for managing tags, email addresses, or any list-based input scenario with built-in validation and suggestions support.

Installation

Install library

npm install @micoblanc/chipster

Basic Usage

Here's a simple example of how to use Chipster:

BasicExample.tsx

import { Chipster } from '@micoblanc/chipster'
 
export default function BasicExample() {
  return (
    <Chipster>
      <Chipster.ItemList />
      <Chipster.Input placeholder="Type and press Enter" />
      <Chipster.Validation
        validationRules={[
          { test: (v) => v.length >= 2, message: 'Min 2 characters' },
          { test: (v) => v.length <= 20, message: 'Max 20 characters' }
        ]}
        maxItems={10}
        allowDuplicates={false}
      />
    </Chipster>
  )
}

Advanced Usage with Suggestions

Here's how to implement Chipster with suggestions and custom icons:

AdvancedExample.tsx

const suggestions = [
  { label: 'JavaScript', icon: '🟨' },
  { label: 'TypeScript', icon: '🔷' },
  { label: 'React', icon: '⚛️' }
]
 
export default function AdvancedExample() {
  const getSuggestions = useCallback((input: string) => {
    return suggestions
      .filter(item => 
        item.label.toLowerCase().includes(input.toLowerCase())
      )
      .map(item => ({
        label: item.label,
        icon: item.icon,
        data: item
      }))
  }, [])
 
  return (
    <Chipster>
      <Chipster.ItemList />
      <Chipster.Input 
        placeholder="Search technologies..."
        className="bg-white rounded-lg"
      />
      <Chipster.Validation
        validationRules={[
          { test: (v) => v.length >= 2, message: 'Min 2 characters' },
          { test: (v) => v.length <= 20, message: 'Max 20 characters' }
        ]}
        maxItems={5}
        transform={(v) => v.toLowerCase().trim()}
      />
      <Chipster.Suggestions getSuggestions={getSuggestions} />
    </Chipster>
  )
}

Components API

Chipster

Main container component that provides context to all child components.

Prop	Type	Description
`className`	`string`	Custom class for the container
`onAdd`	`(text: string) => void`	Callback when an item is added
`onRemove`	`(id: string) => void`	Callback when an item is removed
`defaultValue`	`string[]`	Initial items to populate the input
`disabled`	`boolean`	Disable all interactions
`theme`	`'light' \| 'dark'`	Theme variant
`joiner`	`string \| string[]`	Character(s) that trigger new item creation. Default is Enter and , key only

Chipster.Input

Input component for entering new items.

Prop	Type	Description
`className`	`string`	Custom class for the input
`placeholder`	`string`	Input placeholder text
`onInputChange`	`(value: string) => void`	Input change callback

Chipster.Validation

Validation component for input rules and constraints.

Prop	Type	Description
`validationRules`	`Array<{ test: (value: string) => boolean, message: string }>`	Validation rules
`maxItems`	`number`	Maximum number of items
`allowDuplicates`	`boolean`	Allow duplicate items
`transform`	`(value: string) => string`	Transform input before adding
`onError`	`(error: string) => void`	Error callback

Chipster.Suggestions

Suggestions component for autocomplete functionality.

Prop	Type	Description
`className`	`string`	Custom class for suggestions container
`getSuggestions`	`(input: string) => Array<string \| { label: string, icon?: React.ReactNode, data?: any }>`	Get suggestions function
`onSelect`	`(suggestion: ChipsterSuggestion) => void`	Callback when a suggestion is selected

Chipster.ItemList

Component to display selected items.

Prop	Type	Description
`className`	`string`	Custom class for items container
`itemClassName`	`string`	Custom class for individual items (use `!` modifier to override defaults)
`removeButtonClassName`	`string`	Custom class for remove buttons (use `!` modifier to override defaults)
`iconClassName`	`string`	Custom class for icons (use `!` modifier to override defaults)
`removeIcon`	`ReactNode`	Custom remove button icon

Keyboard Navigation

ArrowLeft/Right: Navigate between chips when input is empty
Backspace: Remove highlighted chip or last chip when input is empty
ArrowUp/Down: Navigate through suggestions
Enter: Select highlighted suggestion
Escape: Clear suggestions and chip highlight

Styling

Chipster uses CSS Modules and can be customized using className props on each component. It also supports dark mode through the theme prop.

Styling Examples

// Basic styling with overrides
<Chipster.ItemList 
  className="flex flex-wrap gap-2"
  itemClassName="!bg-blue-100 !px-3 !py-1" // Use ! to override defaults
  removeButtonClassName="!text-red-500"
/>
 
// Dark theme with custom styles
<Chipster theme="dark">
  <Chipster.ItemList 
    itemClassName="!bg-gray-800 !text-white"
    removeButtonClassName="!text-gray-400"
  />
</Chipster>

mode