# List Selection

URL: https://ark-ui.com/docs/collections/list-selection
LLM: https://ark-ui.com/llms.txt/collections/list-selection

Used for managing selection state in list collections.

---

The `useListSelection` hook manages selection state in lists and collections. It supports single and multiple selection
modes with operations like select, deselect, toggle, and clear.

```tsx
import { createListCollection, useListSelection } from '@ark-ui/react/collection'

const collection = createListCollection({
  items: [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
  ],
})

const selection = useListSelection({
  collection,
  selectionMode: 'single',
  deselectable: true,
})

console.log(selection.selectedValues) // ['apple', 'banana', 'cherry']
```

## Examples

### Basic

By default, the hook supports single selection mode that can be deselected.

> Set `deselectable` to `false` to prevent deselecting the current selection.

```tsx
import { createListCollection, useListSelection } from '@ark-ui/react/collection'
import styles from 'styles/list-selection.module.css'

export const Basic = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
    ],
  })

  const selection = useListSelection({ collection })

  return (
    <div className={styles.Root}>
      <output>Selected: {selection.selectedValues.join(', ') || 'None'}</output>
      {collection.items.map((item) => (
        <label key={item.value} className={styles.Item} data-selected={selection.isSelected(item.value) || undefined}>
          <input
            type="checkbox"
            className={styles.Checkbox}
            checked={selection.isSelected(item.value)}
            onChange={() => selection.select(item.value)}
          />
          <span className={styles.ItemText}>{item.label}</span>
        </label>
      ))}
    </div>
  )
}
```

### Multiple Selection

Set `selectionMode` to `multiple` to allow multiple items to be selected.

```tsx
import { createListCollection, useListSelection } from '@ark-ui/react/collection'
import styles from 'styles/list-selection.module.css'

export const Multiple = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
    ],
  })

  const selection = useListSelection({
    collection,
    selectionMode: 'multiple',
  })

  const handleSelectAll = () => {
    if (selection.isAllSelected()) {
      selection.clear()
    } else {
      selection.setSelectedValues(collection.getValues())
    }
  }

  return (
    <div className={styles.Root}>
      <div className={styles.Header}>
        <span className={styles.Count}>
          {selection.selectedValues.length} of {collection.items.length} selected
        </span>
        <button type="button" className={styles.SelectAllButton} onClick={handleSelectAll}>
          {selection.isAllSelected() ? 'Deselect all' : 'Select all'}
        </button>
      </div>
      {collection.items.map((item) => (
        <label key={item.value} className={styles.Item} data-selected={selection.isSelected(item.value) || undefined}>
          <input
            type="checkbox"
            className={styles.Checkbox}
            checked={selection.isSelected(item.value)}
            onChange={() => selection.select(item.value)}
          />
          <span className={styles.ItemText}>{item.label}</span>
        </label>
      ))}
    </div>
  )
}
```

### Range Selection

Here's an example of how to implement range selection that extends the selection from the first selected item to the
clicked item.

```tsx
import { createListCollection, useListSelection } from '@ark-ui/react/collection'
import styles from 'styles/list-selection.module.css'

export const Range = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
    ],
  })

  const selection = useListSelection({
    collection,
    selectionMode: 'multiple',
  })

  const handleItemClick = (value: string, event: React.MouseEvent) => {
    if (event.shiftKey && selection.firstSelectedValue) {
      selection.extend(selection.firstSelectedValue, value)
    } else if (event.ctrlKey || event.metaKey) {
      selection.toggle(value)
    } else {
      selection.replace(value)
    }
  }

  return (
    <div className={styles.Root}>
      <output>Selected: {selection.selectedValues.join(', ') || 'None'}</output>
      {collection.items.map((item) => (
        <label
          key={item.value}
          className={styles.Item}
          data-selected={selection.isSelected(item.value) || undefined}
          onClick={(e) => handleItemClick(item.value, e)}
        >
          <input type="checkbox" className={styles.Checkbox} checked={selection.isSelected(item.value)} />
          <span className={styles.ItemText}>{item.label}</span>
        </label>
      ))}
      <p className={styles.HelperText}>Click to select • Shift+Click for range • Cmd/Ctrl+Click to toggle</p>
    </div>
  )
}
```

## API Reference

### Props

- **collection** (`ListCollection<T>`) - The collection to manage selection for
- **selectionMode** (`'single' | 'multiple' | 'none'`, default: `'single'`) - The selection mode
- **deselectable** (`boolean`, default: `true`) - Whether selected items can be deselected
- **initialSelectedValues** (`string[]`, default: `[]`) - Initial selected values
- **resetOnCollectionChange** (`boolean`, default: `false`) - Whether to reset selection when collection changes

### Return Value

The hook returns an object with the following properties and methods:

#### State Properties

- **selectedValues** (`string[]`) - Array of currently selected values
- **isEmpty** (`boolean`) - Whether no items are selected
- **firstSelectedValue** (`string | null`) - The first selected value in collection order
- **lastSelectedValue** (`string | null`) - The last selected value in collection order

#### Query Methods

- **isSelected** (`(value: string | null) => boolean`) - Check if a value is selected
- **canSelect** (`(value: string) => boolean`) - Check if a value can be selected
- **isAllSelected** (`() => boolean`) - Check if all items are selected
- **isSomeSelected** (`() => boolean`) - Check if some items are selected

#### Selection Methods

- **select** (`(value: string, forceToggle?: boolean) => void`) - Select a value
- **deselect** (`(value: string) => void`) - Deselect a value
- **toggle** (`(value: string) => void`) - Toggle selection of a value
- **replace** (`(value: string | null) => void`) - Replace selection with a single value
- **extend** (`(anchorValue: string, targetValue: string) => void`) - Extend selection from anchor to target
- **setSelectedValues** (`(values: string[]) => void`) - Set the selected values
- **setSelection** (`(values: string[]) => void`) - Set the selection (alias for setSelectedValues)
- **clear** (`() => void`) - Clear all selections
- **resetSelection** (`() => void`) - Reset selection to initial state