react-picklist-lite

A minimal, framework-agnostic PickList component for React 19 with isolated CSS and a Formik-friendly API. Works on Node.js 20–24.

• Unique CSS prefix: rpkl (no global leakage)
• Controlled component: pass source and target, receive updates via onChange
• TypeScript generics and ESM/CJS builds
• Formik/Yup friendly events
• Another UI library friendly (no design system dependency)
• Dark mode (auto via prefers-color-scheme or force via dark prop)
• Mobile responsive layout
• Built-in SVG icons for actions (move, move all, remove, reorder)
• Search filtering with clear and customizable matcher
• Reorder target list (top / up / down / bottom)
• Per-item disable hook to prevent moving

Install

npm install react-picklist-lite
# or
pnpm add react-picklist-lite

Import the bundled CSS once in your app:

import 'react-picklist-lite/styles.css';

Basic Usage

import { useState } from 'react';
import { PickList } from 'react-picklist-lite';
import 'react-picklist-lite/styles.css';

type User = { id: number; name: string };

export default function Example() {
  const [sourceUsers, setSourceUsers] = useState<User[]>([
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
    { id: 3, name: 'Grace' },
  ]);
  const [targetUsers, setTargetUsers] = useState<User[]>([]);

  return (
    <PickList<User>
      source={sourceUsers}
      target={targetUsers}
      onChange={(e) => {
        setSourceUsers(e.source);
        setTargetUsers(e.target);
      }}
      itemTemplate={(u) => <span>{u.name}</span>}
      getKey={(u) => u.id}
      sourceHeader="Available Users"
      targetHeader="Assigned Users"
      filterable
      reorderable
      showCounts
    />
  );
}

Formik Example

import { Formik, Form } from 'formik';
import * as Yup from 'yup';
import { PickList } from 'react-picklist-lite';
import 'react-picklist-lite/styles.css';

type User = { id: number; name: string };

const validationSchema = Yup.object({
  users: Yup.array().of(
    Yup.object({ id: Yup.number().required(), name: Yup.string().required() })
  ).min(1, 'Pick at least one user')
});

function FormikPickList({ allUsers }: { allUsers: User[] }) {
  return (
    <Formik<{ users: User[] }>
      initialValues={{ users: [] }}
      validationSchema={validationSchema}
      onSubmit={(values) => console.log(values)}
    >
      {({ values, setFieldValue, errors, touched }) => (
        <Form>
          <PickList<User>
            name="users"
            source={allUsers.filter(u => !values.users.some(v => v.id === u.id))}
            target={values.users}
            onChange={(e) => setFieldValue(e.name ?? 'users', e.target)}
            itemTemplate={(u) => <span>{u.name}</span>}
            getKey={(u) => u.id}
            sourceHeader="Available Users"
            targetHeader="Assigned Users"
            filterable
            reorderable
          />
          {touched.users && errors.users ? (
            <div style={{ color: 'red', marginTop: 8 }}>{String(errors.users)}</div>
          ) : null}
          <button type="submit" style={{ marginTop: 12 }}>Submit</button>
        </Form>
      )}
    </Formik>
  );
}

API

export type PickListChangeEvent<T> = {
  source: T[];
  target: T[];
  originalEvent?: React.SyntheticEvent;
  name?: string;
  value?: T[]; // mirrors target for form libs
};

export type PickListProps<T> = {
  source: T[];
  target: T[];
  onChange?: (e: PickListChangeEvent<T>) => void;
  itemTemplate?: (item: T) => React.ReactNode;
  sourceHeader?: React.ReactNode;
  targetHeader?: React.ReactNode;
  className?: string;
  style?: React.CSSProperties;
  name?: string; // forwarded in events
  getKey?: (item: T) => string | number; // stable identity
  sourceEmptyMessage?: React.ReactNode;
  targetEmptyMessage?: React.ReactNode;
  // Optional textual labels used as button titles/tooltips
  moveAllLabel?: string;
  moveSelectedLabel?: string;
  removeSelectedLabel?: string;
  removeAllLabel?: string;
  disabled?: boolean;

  // Advanced options
  filterable?: boolean; // default true
  sourceFilterPlaceholder?: string; // default 'Search...'
  targetFilterPlaceholder?: string; // default 'Search...'
  filterBy?: (item: T, text: string) => boolean; // custom matcher
  reorderable?: boolean; // default true (reorder target)
  showCounts?: boolean; // default true
  dark?: boolean; // force dark theme
  isItemDisabled?: (item: T) => boolean; // prevent selecting/moving
  icons?: Partial<{
    moveSelected: React.ReactNode;
    moveAll: React.ReactNode;
    removeSelected: React.ReactNode;
    removeAll: React.ReactNode;
    up: React.ReactNode; down: React.ReactNode; top: React.ReactNode; bottom: React.ReactNode;
    clear: React.ReactNode; search: React.ReactNode;
  }>;
  ariaLabels?: Partial<{
    moveSelected: string; moveAll: string; removeSelected: string; removeAll: string;
    up: string; down: string; top: string; bottom: string;
    clearFilter: string; sourceSearch: string; targetSearch: string;
  }>;
};

• onChange receives { source, target, name, value }. value mirrors target to simplify integration with form libs.
• Provide a stable getKey for best performance and to avoid duplicates.
• Use dark prop to force dark mode or rely on system theme automatically.

Styling

• All selectors are scoped under the rpkl prefix. No global resets.
• You can theme via CSS vars on .rpkl or a parent:

.rpkl { --rpkl-border: #cbd5e1; --rpkl-selected-bg: #e0e7ff; }

Dark mode variables are applied automatically when the OS prefers dark, or always when you add the rpkl--dark class (the component adds this if you pass dark={true}):

<div className="rpkl rpkl--dark">...</div>

Build (contributors)

npm install
npm run build

What's new in 1.1.0

• Dark mode theme (automatic and opt-in via dark prop)
• Mobile responsive layout
• Search filtering with clear and customizable matcher
• SVG icons for all actions
• Reorder target items (top / up / down / bottom)
• isItemDisabled to lock items from moving/selecting