# Lasso

> Select a loose group by drawing round it: let go and the band pulls tight like an elastic round exactly what it caught, bending in round what it didn’t.

Selecting several things in a grid usually means a rectangle that catches whatever its corners touch, or a click on every one. Lasso lets you draw round them freehand, and then shows you exactly what you got. As you drag, a band follows the hand and anything whose middle falls inside the loop is caught on the spot: a ring and a check pop onto it, and go again if the loop leaves it. Let go and the band pulls tight like an elastic round what it caught, bending in round anything it didn’t, and settles with a little give; a chip riding the top of the band says how many, with a × to let them go. Hold Shift, or start inside the band, to draw another loop: one band tightens round the whole set. Click empty space or press Esc and the band snaps and is gone. Your grid stays yours: mark the items with data-lasso-id, keep your own click to select one, and read the ids from onSelectedChange. Selected items also carry a data-lasso-selected attribute your styles can use.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/lasso.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/lasso
- Registry item (source): https://hairlineui.com/r/lasso.json

## Usage

```tsx
import { Lasso } from "@/components/lasso";

<Lasso onSelectedChange={setSelected}>
  {photos.map((p) => (
    <img key={p.id} data-lasso-id={p.id} src={p.src} alt={p.alt} />
  ))}
</Lasso>
```

## With your own selection state

Controlled: the grid’s own click toggles one photo, the lasso selects many, and both write the same state.

```tsx
"use client";
import * as React from "react";
import { Lasso } from "@/components/lasso";

export function ShootPicker({ photos }: { photos: { id: string; src: string; alt: string }[] }) {
  const [selected, setSelected] = React.useState<string[]>([]);
  const toggle = (id: string) => setSelected((s) => (s.includes(id) ? s.filter((x) => x !== id) : [...s, id]));
  return (
    <>
      <Lasso selected={selected} onSelectedChange={setSelected} className="p-4">
        <div className="grid grid-cols-4 gap-3">
          {photos.map((p) => (
            <button key={p.id} data-lasso-id={p.id} aria-pressed={selected.includes(p.id)} onClick={() => toggle(p.id)}>
              <img src={p.src} alt={p.alt} />
            </button>
          ))}
        </div>
      </Lasso>
      <button disabled={!selected.length} onClick={() => publish(selected)}>
        Publish {selected.length}
      </button>
    </>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | Your items, each with data-lasso-id. They can be anywhere inside. |
| `selected / defaultSelected` | `string[]` | – | The selected ids, controlled or not. |
| `onSelectedChange` | `(ids: string[]) => void` | – | Called when a loop is let go, the selection is added to, or it’s cleared. |
| `itemSelector` | `string` | `"[data-lasso-id]"` | Which descendants can be caught. |
| `color` | `string` | `"var(--primary)"` | The band, rings and checks: any CSS colour. |
| `label` | `(count) => string` | `() => "selected"` | The words after the count on the chip. |
| `sound` | `boolean` | `false` | A soft pop as items are caught and a tick as the band settles. |

## States

- **draw**: Dragging on empty space (5px to start) lays a band behind the hand, with the gap back to the start dashed. Each item whose middle is inside the loop gets a 2px ring and a check that pops in over 260ms; leaving the loop takes them off over 160ms. Once let go, the rings give way to the band and the checks stay.
- **tighten**: On release the band is 120 points under tension only, so it straightens and shortens; what it caught holds it 5px off, and anything it didn’t catch that lies outside it holds it 2px off, so it bends in round those. Photos side by side share one band; one apart gets its own.
- **count**: A chip rides the band’s highest point with the count rolling, and a × to clear.
- **add**: With Shift held, or starting inside the band, the new band starts round both loops and tightens round the whole set.
- **let go**: A click on empty space, Esc or the chip’s × snaps the band: it shrinks and fades in about 180ms, and the checks go.
- **touch**: A 280ms hold, shown as a ring filling under the finger, starts the loop; moving sooner scrolls the page.
- **reduced motion**: The band appears already tight and the checks appear without popping.

## What it handles

A drag rectangle catches whatever its corners clip, and nothing shows what was really selected until you look at each item.

- **Any shape**: Draw round exactly the items you mean, however they’re laid out.
- **You see what’s caught**: Items get a ring and a check while you draw, and the band tightens round just those.
- **Add more**: Shift, or a start inside the band, draws another loop that joins the selection.
- **Your grid, your clicks**: It reads data-lasso-id from your items and leaves your own click handling alone.
- **Touch**: A short hold starts the loop, so a plain swipe still scrolls the page.
- **Controlled or not**: Pass selected to drive it from your state; the band re-wraps whatever you set.

## Replaces

marquee selection, drag to select, rubber band selection, select-many checkboxes, a selection count bar

## Where it fits

- **Photo libraries**: Pick a handful of shots from a shoot to publish, share or delete.
- **File managers**: Select files in a grid or icon view without holding a key.
- **Canvases and boards**: Group cards, notes or nodes that aren’t in a neat rectangle.
- **Maps and scatter plots**: Draw round the stores, pins or points you want to look at.

## Notes

- The lasso is a pointer shortcut on top of your own selection, not a replacement for it: keep a click or a checkbox on each item so keyboards and screen readers can select too. Esc clears while focus is inside, and every change of selection is announced (“4 selected”).
- It starts only on empty space, never on an item, a button, a link or a field, so your items keep their own clicks and drags. Mark anything else to leave alone with data-lasso-ignore.
- The band is a 120-point rope on one canvas over your items; items are rounded boxes it can’t pass through, measured on each press and on resize. The frame loop runs only while the band moves.
- Colours come from your theme (primary by default). Reduced motion settles the band at once and drops the pops.

License: MIT (https://hairlineui.com/license#components)
