---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/start/introduction.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Introduction

ngx-virtual-dnd is a drag-and-drop library for Angular, built for **virtually scrolled lists**. It renders only the rows in view plus a small buffer, so the DOM stays small however long the list grows. Drag and drop still works across the whole list.


Live exampleSortable list with 1,000 items[Open in new tab](/ngx-virtual-dnd/demo/examples/quick-start/)

Try it: drag a row, or focus one with Tab
, press Space
 and move it with the arrow keys. The list holds 1,000 tasks, but only about a dozen rows are in the DOM at any time.
## Why a separate library

Most drag-and-drop libraries work out the drop position by measuring sibling elements in the DOM. With virtual scrolling most siblings do not exist, so those libraries drop items in the wrong place, or cannot scroll to a target that has not been rendered yet.

ngx-virtual-dnd works from geometry instead. At drag start it records the position and size of each drop target. While you drag, it compares the pointer with those recorded bounds and calculates the drop index from the scroll offset and row heights. See [How it works](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/how-it-works.md) for details. The approach was inspired by [react-virtualized-dnd](https://github.com/forecast-it/react-virtualized-dnd).

## Features

- **Virtual scrolling** with fixed or [dynamic item heights](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md)
- **[Multiple lists](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md)** that exchange items within a group
- **[Page-level scrolling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md)**, including Ionic `ion-content`
- **[Auto-scroll](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/auto-scroll.md)** near container edges, with configurable speed and threshold
- **[Drag handles, delays, axis locking and constraints](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md)**
- **[Custom previews and placeholders](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md)**
- **[Shift animations and haptics](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md)**, opt-in
- **[Keyboard and screen reader support](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md)**
- **Angular 21+:** standalone components, signals, `OnPush`-friendly

## When to use it

Use ngx-virtual-dnd for **vertical lists**, such as sortable lists and kanban-style boards, especially when a list can grow to hundreds or thousands of items.

It is not a general-purpose drag-and-drop toolkit. Freeform canvases, grids with 2D reordering and dragging files from the desktop are out of scope. See [Known limitations](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md).

## Next steps

- [Install the package](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/installation.md)
- [Build a sortable list](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md) in a few minutes
- Moving from `@angular/cdk/drag-drop`? See [Coming from Angular CDK](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/coming-from-cdk.md)
- Using an AI coding assistant? [Install the agent skill](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/ai-assistants.md)



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/start/installation.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Installation


```sh [npm]
npm install ngx-virtual-dnd
```

```sh [yarn]
yarn add ngx-virtual-dnd
```

```sh [pnpm]
pnpm add ngx-virtual-dnd
```

```sh [bun]
bun add ngx-virtual-dnd
```

```sh [deno]
deno add npm:ngx-virtual-dnd
```

## Requirements

| Requirement       | Version                                 |
| ----------------- | --------------------------------------- |
| `@angular/core`   | `^21.0.0 \|\| ^22.0.0`                  |
| `@angular/common` | `^21.0.0 \|\| ^22.0.0`                  |
| Browsers          | Latest Chrome, Edge, Firefox and Safari |

Its only runtime dependency is `tslib`.

## Imports

Every component, directive, utility and type is exported from the package root. They are all standalone, so you import them directly in the component that uses them:

```ts
import {
  DraggableDirective,
  DragPreviewComponent,
  DropEvent,
  DroppableGroupDirective,
  moveItem,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';
```

There are no providers to register and no global stylesheet to include. The one optional token, `VDND_ANIMATION_CONFIG`, turns on [shift and drop animations](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md). The library only sets the layout styles that virtual scrolling needs. How items, lists and the drop placeholder look is up to your app. See [Styling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/styling.md) for the CSS classes the library adds.

## Next

Build your first list in the [Quick start](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Quick start

This page builds a sortable list of 1,000 tasks. `<vdnd-sortable-list>` combines the drop target, the virtual scroller and the drop placeholder, so it is the right starting point for most apps.


Live exampleSortable list with 1,000 items[Open in new tab](/ngx-virtual-dnd/demo/examples/quick-start/)

## The code

```ts file="<root>/src/app/examples/quick-start/quick-start.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  reorderItems,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Task {
  id: string;
  title: string;
}

@Component({
  selector: 'app-quick-start-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  template: `
    <div vdndGroup="tasks">
      <!-- Declared inside vdndGroup, so every draggable inherits the group -->
      <ng-template #taskTpl let-task>
        <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
      </ng-template>

      <vdnd-sortable-list
        class="list"
        droppableId="backlog"
        [items]="tasks()"
        [itemHeight]="48"
        [containerHeight]="336"
        [itemIdFn]="taskId"
        [itemTemplate]="taskTpl"
        (drop)="onDrop($event)"
      />
    </div>

    <!-- Renders the element that follows the pointer. Place it once. -->
    <vdnd-drag-preview />
  `,
})
export class QuickStartExampleComponent {
  // 1,000 items; only the visible rows are in the DOM.
  readonly tasks = signal<Task[]>(
    Array.from({ length: 1000 }, (_, i) => ({ id: `task-${i + 1}`, title: `Task ${i + 1}` })),
  );

  readonly taskId = (task: Task): string => task.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tasks);
  }
}

```

## What each part does

1. **`vdndGroup="tasks"`** names the group that draggables and drop targets belong to. Items can only move between drop targets in the same group. A group is required even for a single list; without one, dragging is disabled.
2. **The item template** is declared _inside_ the `vdndGroup` element. Angular templates resolve dependency injection where they are declared, so this is how each draggable finds its group.
3. **`[vdndDraggable]="task.id"`** makes each row draggable. The ID must equal what `itemIdFn` returns for that item, and it must sit on the template's root element.
4. **`<vdnd-sortable-list>`** renders the visible rows. `itemHeight` is the row height in pixels and `containerHeight` is the height of the scroll area.
5. **`(drop)`** fires when an item is dropped. The library never changes your data. `reorderItems()` applies the move to the `tasks` signal.
6. **`<vdnd-drag-preview />`** renders the element that follows the pointer. Place it once, anywhere in the template.

:::tip Keyboard support is built in
Every draggable can be focused with Tab
. Space
 picks it up, the arrow keys move it, and Space
 or Enter
 drops it. See [Accessibility](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md)
.
:::
## Styles

The library does not style rows or the drop placeholder, so the code above renders plain text rows and an invisible placeholder. Add at least this CSS:

```css
/* In the component's styles: the row template is declared in its template */
.row {
  display: flex;
  align-items: center;
  box-sizing: border-box;
  height: 48px; /* exactly itemHeight */
  padding: 0 16px;
  border-bottom: 1px solid #e2e7f0;
  background: #fff;
}

/* In a global stylesheet (styles.css): the library renders the placeholder */
.vdnd-drag-placeholder-visible {
  box-sizing: border-box;
  border: 1.5px dashed #0e9488;
  background: #e4f3f2;
}
```

:::warning Rows must be exactly itemHeight tall
With fixed heights, every row must be exactly `itemHeight` pixels tall, borders and padding included. Otherwise the rows on screen drift away from the positions the list calculates, and items drop in the wrong place.
:::

For rows that differ in height, see [Dynamic item heights](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md). [Styling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/styling.md) lists every class the library adds.

## Next steps

- [Core concepts](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md): what groups, draggables and droppables are, and the rules that keep them working
- [Multiple lists](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md): move items between lists
- [Choosing a component](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/choosing-a-component.md): when to use something other than `<vdnd-sortable-list>`



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/start/coming-from-cdk.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Coming from Angular CDK

The Angular CDK's drag and drop (`@angular/cdk/drag-drop`) finds drop positions by measuring the rendered siblings, so it does not support virtual scrolling: in a `cdk-virtual-scroll-viewport`, most siblings are not rendered. ngx-virtual-dnd covers the same sortable-list use cases with virtual scrolling. This page maps one API to the other.

## A sortable list, before and after

With the CDK:

```angular-html
<div cdkDropList (cdkDropListDropped)="drop($event)">
  @for (task of tasks; track task.id) {
    <div class="row" cdkDrag>{{ task.title }}</div>
  }
</div>
```

```ts
drop(event: CdkDragDrop<Task[]>): void {
  moveItemInArray(this.tasks, event.previousIndex, event.currentIndex);
}
```

With ngx-virtual-dnd:

```angular-html
<div vdndGroup="tasks">
  <ng-template #taskTpl let-task>
    <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
  </ng-template>

  <vdnd-sortable-list
    droppableId="tasks"
    [items]="tasks()"
    [itemHeight]="48"
    [containerHeight]="400"
    [itemIdFn]="taskId"
    [itemTemplate]="taskTpl"
    (drop)="onDrop($event)"
  />
</div>

<vdnd-drag-preview />
```

```ts
onDrop(event: DropEvent): void {
  reorderItems(event, this.tasks); // tasks is a WritableSignal<Task[]>
}
```

The differences that matter:

- **The list renders the rows.** You pass the items and a row template instead of writing the `@for` loop, because only the visible rows are rendered.
- **Every list needs a group**, even a single one. A group replaces `cdkDropListConnectedTo` and `cdkDropListGroup`: lists in the same group exchange items.
- **Items and lists have string IDs.** The draggable's ID must equal what `itemIdFn` returns for its item.
- **The preview is rendered once**, by `<vdnd-drag-preview />`, not per item.
- **Rows have a known height.** Pass it as `itemHeight`, or turn on [`dynamicItemHeight`](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md) to measure them.
- **Your data is never mutated.** The helpers update signals or return new arrays.

[Core concepts](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md) explains each of these.

## API mapping

### Lists and items

| Angular CDK                                     | ngx-virtual-dnd                                                                                                                                                                    |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cdkDropList` with an `@for` of `cdkDrag` items | `<vdnd-sortable-list>`, or [another list component](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/choosing-a-component.md)                                          |
| `cdkDrag`                                       | `[vdndDraggable]="item.id"`                                                                                                                                                        |
| `cdkDropListConnectedTo`, `cdkDropListGroup`    | `vdndGroup="name"` around the lists                                                                                                                                                |
| `cdkDragData`                                   | `[vdndDraggableData]`                                                                                                                                                              |
| `cdkDropListData`                               | `droppableData` (`vdndDroppableData` on `vdndDroppable`). Lists are usually told apart by `droppableId`                                                                            |
| `cdkDragHandle`                                 | `dragHandle="<CSS selector>"` on the draggable. See [Drag handles](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#drag-handles)                       |
| `cdkDragDisabled`, `cdkDropListDisabled`        | `disabled`                                                                                                                                                                         |
| `cdkDragStartDelay`                             | `dragDelay`                                                                                                                                                                        |
| `dragStartThreshold` (`CDK_DRAG_CONFIG`)        | `dragThreshold`                                                                                                                                                                    |
| `cdkDragLockAxis`                               | `lockAxis`, but **inverted**: it names the frozen axis. See [Axis locking](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#axis-locking)               |
| `cdkDragBoundary`                               | `constrainToContainer` on the list. See [Constraining to the container](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#constraining-to-the-container) |
| `*cdkDragPreview`                               | `<vdnd-drag-preview [previewTemplate]>`. See [Custom preview](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md#custom-preview)                |
| `*cdkDragPlaceholder`                           | No template. Style the `.vdnd-drag-placeholder` class                                                                                                                              |
| `cdkDropListEnterPredicate`                     | Bind `disabled` from the drag state. See [Accepting only some items](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md#accepting-only-some-items)     |
| `cdkDropListOrientation`                        | Lists are vertical; `horizontal` and `mixed` are not supported                                                                                                                     |
| `cdkDropListSortingDisabled`                    | Not supported                                                                                                                                                                      |

### Events

| Angular CDK                                   | ngx-virtual-dnd                                                                                  |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `(cdkDropListDropped)`                        | `(drop)`, on the destination list only                                                           |
| `(cdkDragStarted)`, `(cdkDragEnded)`          | `(dragStart)`, `(dragEnd)` on the draggable                                                      |
| `(cdkDropListSorted)`                         | `(placeholderMove)`                                                                              |
| `(cdkDropListEntered)`, `(cdkDropListExited)` | No output. Read `activeDroppableId()` from `DragStateService`, or style `.vdnd-droppable-active` |

`CdkDragDrop` maps to `DropEvent` like this:

| `CdkDragDrop`       | `DropEvent`               |
| ------------------- | ------------------------- |
| `previousIndex`     | `source.index`            |
| `currentIndex`      | `destination.index`       |
| `previousContainer` | `source.droppableId`      |
| `container`         | `destination.droppableId` |
| `item.data`         | `source.data`             |
| `container.data`    | `destination.data`        |

The indexes mean the same as in the CDK: remove the item at `source.index`, then insert it at `destination.index`.

Releasing outside every list emits no `(drop)` at all. `(dragEnd)` reports it with `destinationIndex: null`.

### Helpers

| Angular CDK                                       | ngx-virtual-dnd                                         |
| ------------------------------------------------- | ------------------------------------------------------- |
| `moveItemInArray(array, from, to)`                | `reorderItems(event, listSignal)`                       |
| `transferArrayItem(from, to, fromIndex, toIndex)` | `moveItem(event, { todo: this.todo, done: this.done })` |
| Both, for immutable state                         | `applyMove(event, lists)` returns new arrays            |

`moveItem()` handles moves within one list and between lists, so one handler serves every list. See [Handling drops](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md).

### CSS classes

| Angular CDK               | ngx-virtual-dnd                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `.cdk-drag-preview`       | `.vdnd-drag-preview`                                                                |
| `.cdk-drag-placeholder`   | `.vdnd-drag-placeholder`                                                            |
| `.cdk-drag-animating`     | `.vdnd-drag-preview-dropping`, while the preview glides into place                  |
| `.cdk-drop-list-dragging` | `.vdnd-droppable-active` on the targeted list, `body.vdnd-dragging` during any drag |
| `.cdk-drag-disabled`      | `.vdnd-draggable-disabled`                                                          |
| `.cdk-drop-list-disabled` | `.vdnd-droppable-disabled`                                                          |

CDK apps usually animate rows with a CSS `transition` on `.cdk-drag`. Remove it when you migrate: here, animations are opt-in through [`VDND_ANIMATION_CONFIG`](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md), and a transition on rows competes with them.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Core concepts

Every setup, from one list to a full board, is made of the same four parts.

| Concept       | What it is                                                                                      | Declared with                                                    |
| ------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Droppable** | A list that items can be dropped into, identified by an ID.                                     | `vdndDroppable="id"`, or `droppableId` on `<vdnd-sortable-list>` |
| **Draggable** | An item that can be picked up, identified by an ID.                                             | `[vdndDraggable]="item.id"`                                      |
| **Group**     | A name linking draggables and droppables. Items move only between droppables of the same group. | `vdndGroup="name"` on an ancestor element                        |
| **Preview**   | The element that follows the pointer during a drag.                                             | `<vdnd-drag-preview />`, placed once                             |

## Life of a drag

1. The user presses on a draggable and moves past the drag threshold (5 px by default), or presses <kbd>Space</kbd> on a focused draggable.
2. The dragged element is hidden with `display: none`. The preview appears under the pointer and an empty **placeholder** marks the drop position in the target list.
3. As the pointer moves, the library works out which droppable is under it and at which index the item would land. Near the edges of a scrollable list it scrolls automatically.
4. On release, the dragged draggable emits `(dragEnd)`, whether the item was dropped or not. If it was dropped, the **destination** droppable then emits `(drop)` with the source and destination indexes. Both fire before the next render.
5. Your handler updates the data. The library never changes your arrays.

```ts
onDrop(event: DropEvent): void {
  // Same list or across lists, keyed by droppable ID
  moveItem(event, { todo: this.todo, done: this.done });
}
```

See [Handling drops](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md) for the event shape and the helper functions.

## Rules that fail silently

Breaking any of these rules causes no build error. The list just does not drag, or drops items in the wrong place.

1. **Every draggable and droppable needs a group**, even when there is only one list. Wrap them in `vdndGroup`, or set `vdndDraggableGroup` / `vdndDroppableGroup` (`group` on `<vdnd-sortable-list>`). Without a group, dragging is disabled and the only hint is a warning in the console in dev mode.
2. **Declare the item `<ng-template>` inside the `vdndGroup` element.** Templates resolve injection where they are declared, not where they are rendered.
3. **The draggable ID must equal the list's item ID**: what `itemIdFn(item)` returns, or the `trackBy` key for `*vdndVirtualFor`. IDs are strings, so convert numeric IDs the same way in both places.
4. **Draggable IDs must be unique across all lists**, and droppable IDs must be unique on the page.
5. **Render `<vdnd-drag-preview />` once.** Without it, dragging works but nothing follows the pointer.
6. **Give every virtual list a height**, with `containerHeight` or with CSS. A list without a height collapses to 0 px. To size `<vdnd-sortable-list>` with CSS, set the height on its inner `vdnd-virtual-scroll` from a global stylesheet.
7. **Put `vdndDraggable` on the root element of the item template.** A wrapper around it would stay in the list during the drag and leave a gap.
8. **Bind `(drop)` on every list that can receive items.** It fires on the destination only.
9. **With fixed heights, make every row exactly `itemHeight` pixels tall**, borders and padding included. Otherwise the rows on screen drift away from the positions the list calculates. For rows of different heights, use [`dynamicItemHeight`](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md).

[Troubleshooting](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/troubleshooting.md) maps common symptoms back to these rules.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Handling drops

The library never mutates your data. When an item is dropped, the destination droppable emits a `DropEvent`, and you apply the move.

## The drop event

```ts
interface DropEvent {
  source: {
    draggableId: string;
    droppableId: string;
    index: number; // where the item was
    data?: unknown; // vdndDraggableData
  };
  destination: {
    droppableId: string;
    placeholderId: string; // deprecated: always END_OF_LIST; use index for the position
    index: number; // where the item goes, after it is removed from the source
    data?: unknown; // vdndDroppableData (droppableData on vdnd-sortable-list)
  };
}
```

`destination.index` is the insertion index **after** the item is removed from its source. "Remove at `source.index`, then insert at `destination.index`" is always correct, whether the move stays in one list or crosses lists.

With virtual scrolling most items are not in the DOM, so always work from the event's indexes, never from DOM order.

## Helpers

| Function                      | Use when                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `moveItem(event, lists)`      | Your lists are `WritableSignal<T[]>`. Works within one list and across lists.  |
| `reorderItems(event, list)`   | A single signal-based list. Reorders only.                                     |
| `applyMove(event, lists)`     | Immutable state (a store, a service). Takes plain arrays and returns new ones. |
| `isNoOpDrop(event)`           | `true` when the item was dropped back where it started.                        |
| `insertAt(list, item, index)` | Returns a new array with the item inserted.                                    |
| `removeAt(list, index)`       | Returns a new array without the item at `index`.                               |

### Signals

```ts
onDrop(event: DropEvent): void {
  moveItem(event, { todo: this.todo, done: this.done });
}
```

### Stores and immutable state

```ts
onDrop(event: DropEvent): void {
  if (isNoOpDrop(event)) return;

  const lists = applyMove(event, {
    todo: this.store.todo(),
    done: this.store.done(),
  });
  this.store.setLists(lists);
}
```

`applyMove()` returns a shallow copy of the record, with new arrays for the lists that changed.

### Saving to a server

Apply the move straight away and roll back if the request fails:

```ts
onDrop(event: DropEvent): void {
  if (isNoOpDrop(event)) return;

  const previous = { todo: this.todo(), done: this.done() };
  moveItem(event, { todo: this.todo, done: this.done });

  this.api
    .moveTask(event.source.draggableId, event.destination.droppableId, event.destination.index)
    .subscribe({
      error: () => {
        this.todo.set(previous.todo);
        this.done.set(previous.done);
      },
    });
}
```

## Drag lifecycle events

Draggables also emit `(dragStart)` and `(dragEnd)`:

```angular-html
<div [vdndDraggable]="task.id" (dragStart)="onDragStart($event)" (dragEnd)="onDragEnd($event)">
  {{ task.title }}
</div>
```

`(dragEnd)`
 fires after every drag, dropped or not. Check `event.destinationIndex === null`
 to detect "no drop": the drag was cancelled (for example with Escape
), or released outside every droppable or over a disabled one. Don't rely on `cancelled`
, which is `true`
 only in the first case. [`DragEndEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#dragendevent)
 lists every way a drag can end without a drop.
During a drag, droppables and `<vdnd-sortable-list>` emit `(placeholderMove)` each time the placeholder moves within them. Use it for per-step feedback such as haptics. See [Animations and haptics](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md#placeholder-move-events).

To react to drags anywhere in the app, for example to show a hint, inject `DragStateService` and read its signals, such as `isDragging()` and `activeDroppableId()`. See the [API reference](https://gultyayev.github.io/ngx-virtual-dnd/api/services.md).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Multiple lists

Lists that share a **group** exchange items. Drag a row from one column to the other:


Live exampleTwo lists sharing a group[Open in new tab](/ngx-virtual-dnd/demo/examples/multiple-lists/)

```ts file="<root>/src/app/examples/multiple-lists/multiple-lists.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  moveItem,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Task {
  id: string;
  title: string;
}

const createTasks = (prefix: string, count: number): Task[] =>
  Array.from({ length: count }, (_, i) => ({
    id: `${prefix}-${i + 1}`,
    title: `${prefix === 'todo' ? 'Task' : 'Done'} ${i + 1}`,
  }));

@Component({
  selector: 'app-multiple-lists-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  template: `
    <!-- Both lists share the "board" group, so items can move between them -->
    <div class="board" vdndGroup="board">
      <ng-template #taskTpl let-task>
        <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
      </ng-template>

      <section class="column">
        <h3>
          To do <span>{{ todo().length }}</span>
        </h3>
        <vdnd-sortable-list
          class="list"
          droppableId="todo"
          [items]="todo()"
          [itemHeight]="48"
          [containerHeight]="288"
          [itemIdFn]="taskId"
          [itemTemplate]="taskTpl"
          (drop)="onDrop($event)"
        />
      </section>

      <section class="column">
        <h3>
          Done <span>{{ done().length }}</span>
        </h3>
        <vdnd-sortable-list
          class="list"
          droppableId="done"
          [items]="done()"
          [itemHeight]="48"
          [containerHeight]="288"
          [itemIdFn]="taskId"
          [itemTemplate]="taskTpl"
          (drop)="onDrop($event)"
        />
      </section>
    </div>

    <vdnd-drag-preview />
  `,
})
export class MultipleListsExampleComponent {
  readonly todo = signal<Task[]>(createTasks('todo', 200));
  readonly done = signal<Task[]>(createTasks('done', 200));

  readonly taskId = (task: Task): string => task.id;

  // (drop) fires on the destination list only, so both lists bind it.
  onDrop(event: DropEvent): void {
    moveItem(event, { todo: this.todo, done: this.done });
  }
}

```

Three details make this work:

- Both `<vdnd-sortable-list>` elements are inside the same `vdndGroup`, and so is the shared item template.
- **Both lists bind `(drop)`.** The event fires on the destination list only, so a list without a handler silently rejects items.
- `moveItem()` receives every list, keyed by `droppableId`. It handles moves within a list as well as between lists. If a droppable ID is missing from the map, the drop is ignored and a warning is logged in dev mode.

## A board with any number of columns

Keep one signal per column and build the map for `moveItem()` from your column list:

```ts
interface Column {
  id: string;
  title: string;
  tasks: WritableSignal<Task[]>;
}

readonly columns: Column[] = [
  { id: 'todo', title: 'To do', tasks: signal([]) },
  { id: 'doing', title: 'In progress', tasks: signal([]) },
  { id: 'done', title: 'Done', tasks: signal([]) },
];

readonly lists = Object.fromEntries(this.columns.map((c) => [c.id, c.tasks]));

onDrop(event: DropEvent): void {
  moveItem(event, this.lists);
}
```

```angular-html
<div class="board" vdndGroup="board">
  <ng-template #taskTpl let-task>
    <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
  </ng-template>

  @for (column of columns; track column.id) {
    <section>
      <h3>{{ column.title }}</h3>
      <vdnd-sortable-list
        [droppableId]="column.id"
        [items]="column.tasks()"
        [itemHeight]="48"
        [containerHeight]="480"
        [itemIdFn]="taskId"
        [itemTemplate]="taskTpl"
        (drop)="onDrop($event)"
      />
    </section>
  }
</div>
```

Draggable IDs must be unique across **all** columns, because drag state is shared across the whole app.

## Controlling where items can go

| Goal                                    | How                                                                          |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| Lists that never exchange items         | Put them in different groups (separate `vdndGroup` elements)                 |
| A list that temporarily accepts nothing | `[disabled]="true"` on the list or on `vdndDroppable`                        |
| Items that cannot be moved              | `[disabled]="true"` on the draggable                                         |
| Accept only some items                  | Bind `disabled` from the drag state, see [below](#accepting-only-some-items) |

A disabled droppable is skipped completely. The pointer passes through it to whatever is underneath, and the keyboard's left and right arrows skip it. See [Drag behavior](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#disabling).

Releasing over nothing, or over a disabled list, emits no `(drop)`. The item returns to where it started.

## Accepting only some items

There is no predicate input that rejects some items. Returning early from `(drop)` keeps your data unchanged, but during the drag the target list still opens a slot for the item, so the user sees a drop that then does not happen.

Instead, disable the list while an item it does not accept is being dragged. `DragStateService` tells you which item that is, and a droppable whose `disabled` changes mid-drag is skipped from the next frame:

```ts
readonly #dragState = inject(DragStateService);

// Only tasks with an assignee can move to "Done"
readonly doneRejectsDrag = computed(() => {
  const task = this.#dragState.draggedItem()?.data as Task | undefined;
  return task !== undefined && !task.assignee;
});
```

```angular-html
<ng-template #taskTpl let-task>
  <div class="row" [vdndDraggable]="task.id" [vdndDraggableData]="task">{{ task.title }}</div>
</ng-template>

<vdnd-sortable-list droppableId="done" [disabled]="doneRejectsDrag()" ... />
```

The pointer then passes over the list without a placeholder, and the keyboard's left and right arrows skip it. Style `.vdnd-droppable-disabled` to show that the list does not accept the item.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/choosing-a-component.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Choosing a component

The first three options support dynamic heights, pointer auto-scroll and moving items between lists. They differ in how much markup you control and in which element scrolls. Only `<vdnd-sortable-list>` and `<vdnd-virtual-scroll>` scroll to follow a keyboard drag.

| You want                                                         | Use                                                                |
| ---------------------------------------------------------------- | ------------------------------------------------------------------ |
| A sortable list with the least code                              | [`<vdnd-sortable-list>`](#sortable-list)                           |
| Your own markup around the scroller, or programmatic scrolling   | [`vdndDroppable` + `<vdnd-virtual-scroll>`](#low-level-scroller)   |
| A list that scrolls with the page, or inside Ionic `ion-content` | [`vdndScrollable` + `<vdnd-virtual-content>`](#page-level-scroll)  |
| A self-scrolling building block for a structural directive       | [`<vdnd-virtual-viewport>` + `*vdndVirtualFor`](#virtual-viewport) |

## Sortable list

The default. One element combines the droppable, the virtual scroller and the placeholder. It also keeps the dragged item rendered while it is scrolled out of view. See the [Quick start](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md).

```angular-html
<vdnd-sortable-list
  droppableId="tasks"
  [items]="tasks()"
  [itemHeight]="48"
  [containerHeight]="400"
  [itemIdFn]="taskId"
  [itemTemplate]="taskTpl"
  (drop)="onDrop($event)"
/>
```

## Low-level scroller

Put `vdndDroppable` on your own element and place `<vdnd-virtual-scroll>` inside it. Use this when you need a wrapper with its own layout, the `stickyItemIds` input, or the scrolling methods (`scrollTo`, `scrollToIndex`, `scrollBy`).

```angular-html
<div vdndGroup="tasks">
  <ng-template #taskTpl let-task>
    <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
  </ng-template>

  <div class="panel" vdndDroppable="tasks" (drop)="onDrop($event)">
    <vdnd-virtual-scroll
      droppableId="tasks"
      [items]="tasks()"
      [itemHeight]="48"
      [containerHeight]="400"
      [itemIdFn]="taskId"
      [itemTemplate]="taskTpl"
    />
  </div>
</div>
```

Pass the same ID to `vdndDroppable` and to `droppableId` on `<vdnd-virtual-scroll>`. The scroller needs it to show the placeholder. To scroll from code, get the component with `viewChild(VirtualScrollContainerComponent)`.

## Page-level scroll

When the list scrolls together with the page, headers and footers, the scroll container is an element you own. Mark it with `vdndScrollable` and render items with `<vdnd-virtual-content>` and `*vdndVirtualFor`. See [Page-level scrolling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md).

## Virtual viewport

`<vdnd-virtual-viewport>` is a lower-level building block: a self-scrolling container for `*vdndVirtualFor` that positions all rows with a single transform. Children inherit `itemHeight` and `dynamicItemHeight` from it. For drag and drop, put `vdndDroppable` on the viewport itself; `*vdndVirtualFor` inherits its ID.

```angular-html
<div vdndGroup="tasks">
  <vdnd-virtual-viewport
    class="viewport"
    vdndDroppable="tasks"
    [itemHeight]="48"
    (drop)="onDrop($event)"
  >
    <ng-container *vdndVirtualFor="let task of tasks(); trackBy: trackById">
      <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
    </ng-container>
  </vdnd-virtual-viewport>
</div>
```

Give the viewport a height with CSS (for example `.viewport { height: 400px; }`).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Dynamic item heights

When rows have different heights, set `[dynamicItemHeight]="true"`. `itemHeight` then becomes the **estimate** for rows that have not been rendered yet.


Live exampleList with variable row heights[Open in new tab](/ngx-virtual-dnd/demo/examples/dynamic-height/)

```ts file="<root>/src/app/examples/dynamic-height/dynamic-height.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  reorderItems,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Note {
  id: string;
  title: string;
  body: string;
}

const SENTENCE = 'Rows are measured with a ResizeObserver as they render. ';

@Component({
  selector: 'app-dynamic-height-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  template: `
    <div vdndGroup="notes">
      <ng-template #noteTpl let-note>
        <div class="row note" [vdndDraggable]="note.id">
          <span class="note-title">{{ note.title }}</span>
          <span class="note-body">{{ note.body }}</span>
        </div>
      </ng-template>

      <!-- itemHeight is only the estimate for rows that have not been measured yet -->
      <vdnd-sortable-list
        class="list"
        droppableId="notes"
        [items]="notes()"
        [itemHeight]="72"
        [dynamicItemHeight]="true"
        [containerHeight]="336"
        [itemIdFn]="noteId"
        [itemTemplate]="noteTpl"
        (drop)="onDrop($event)"
      />
    </div>

    <vdnd-drag-preview />
  `,
})
export class DynamicHeightExampleComponent {
  readonly notes = signal<Note[]>(
    Array.from({ length: 500 }, (_, i) => ({
      id: `note-${i + 1}`,
      title: `Note ${i + 1}`,
      body: SENTENCE.repeat((i % 4) + 1).trim(),
    })),
  );

  readonly noteId = (note: Note): string => note.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.notes);
  }
}

```

## How it works

- Rendered rows are measured with a `ResizeObserver`. If a row's content changes height later, the list updates.
- Heights are cached **by item ID** in each list, so they survive reordering. An item moved into another list is measured again there, starting from that list's estimate.
- Offsets are kept as prefix sums, so finding the row at a scroll position is a binary search (O(log n)). A measured height only invalidates the offsets after its row, and they are recomputed only as far as a lookup reaches, so measuring rows while scrolling a long list stays cheap.
- `dynamicItemHeight` and `itemHeight` can change at runtime. The list then starts again from the estimate and measures the rendered rows anew. Turning `dynamicItemHeight` off stops measuring.

Two rules from [Core concepts](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md#rules-that-fail-silently) matter most here. The draggable ID must equal the item ID, and `vdndDraggable` must be on the template's root element. The list uses both to find the element it measures.

## Choosing the estimate

Pick an estimate close to your typical row height. A poor estimate still works, but the scrollbar size and position shift more as rows are measured.

## Other components

The same input exists on every virtual container:

```angular-html
<vdnd-virtual-scroll [itemHeight]="80" [dynamicItemHeight]="true" ... />

<vdnd-virtual-content [itemHeight]="80" [dynamicItemHeight]="true" vdndDroppable="notes">
  ...
</vdnd-virtual-content>

<!-- *vdndVirtualFor directly inside a vdndScrollable, with no parent viewport -->
<ng-container
  *vdndVirtualFor="let note of notes(); itemHeight: 80; dynamicItemHeight: true; trackBy: trackById"
>
  ...
</ng-container>
```

Inside `<vdnd-virtual-content>` or `<vdnd-virtual-viewport>`, `*vdndVirtualFor` inherits `itemHeight` and `dynamicItemHeight` from its parent. Directly inside a `vdndScrollable`, it positions each row absolutely at its measured offset (see [VirtualForDirective](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#virtualfordirective)).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Page-level scrolling

Sometimes the list is not its own scroll box: it scrolls together with a page header, other content and a footer. Mark the element that actually scrolls with `vdndScrollable`, and render items with `<vdnd-virtual-content>` and `*vdndVirtualFor`.


Live exampleList that scrolls with its header and footer[Open in new tab](/ngx-virtual-dnd/demo/examples/page-scroll/)

```ts file="<root>/src/app/examples/page-scroll/page-scroll.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  ContentHeaderDirective,
  DraggableDirective,
  DragPreviewComponent,
  DropEvent,
  DroppableDirective,
  DroppableGroupDirective,
  reorderItems,
  ScrollableDirective,
  VirtualContentComponent,
  VirtualForDirective,
} from 'ngx-virtual-dnd';

interface Task {
  id: string;
  title: string;
}

@Component({
  selector: 'app-page-scroll-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ScrollableDirective,
    VirtualContentComponent,
    VirtualForDirective,
    ContentHeaderDirective,
    DraggableDirective,
    DroppableDirective,
    DroppableGroupDirective,
    DragPreviewComponent,
  ],
  template: `
    <!-- The element that scrolls: it needs a height and overflow: auto -->
    <div class="page" vdndScrollable>
      <div vdndGroup="today">
        <vdnd-virtual-content [itemHeight]="48" vdndDroppable="today" (drop)="onDrop($event)">
          <!-- Measured automatically, and scrolls together with the rows -->
          <h3 class="page-header" vdndContentHeader>Today</h3>

          <ng-container *vdndVirtualFor="let task of tasks(); trackBy: trackById">
            <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
          </ng-container>
        </vdnd-virtual-content>
      </div>

      <footer class="page-footer">Regular content after the list</footer>
    </div>

    <vdnd-drag-preview />
  `,
})
export class PageScrollExampleComponent {
  readonly tasks = signal<Task[]>(
    Array.from({ length: 500 }, (_, i) => ({ id: `task-${i + 1}`, title: `Task ${i + 1}` })),
  );

  readonly trackById = (_index: number, task: Task): string => task.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tasks);
  }
}

```

The element marked `vdndScrollable` must be the one that scrolls, so give it a height and an overflow:

```css
.page {
  height: 100vh; /* the example uses 400px */
  overflow: auto;
}
```

- `<vdnd-virtual-content>` must be inside the `vdndScrollable` element.
- Inside `<vdnd-virtual-content>`, `*vdndVirtualFor` inherits `itemHeight` and `dynamicItemHeight` from it, and the droppable ID from the enclosing `vdndDroppable`. Only `trackBy` is required.
- `vdndContentHeader` marks a header inside the component. Its height is measured and used as the list's top offset. If the header lives outside the component, pass its height with `[contentOffset]` instead.
- Auto-scroll uses the `vdndScrollable` element, so dragging near the top or bottom of the page scrolls it.

## Sticky headers and footers

A header or footer with `position: sticky` inside the scroll container stays on screen while the rows scroll behind it. The drag can't tell it covers the container, so tell it with `scrollInsetTop` and `scrollInsetBottom`: the height in pixels each covers. Measure them however suits your layout:

```angular-html
<div
  vdndScrollable
  [scrollInsetTop]="headerHeight()"
  [scrollInsetBottom]="footerHeight()"
>
  <header class="sticky-header">...</header>
  <vdnd-virtual-content [itemHeight]="72" [contentOffset]="headerHeight()" vdndDroppable="tasks">
    ...
  </vdnd-virtual-content>
  <footer class="sticky-footer">...</footer>
</div>
```

```css
.sticky-header {
  position: sticky;
  top: 0;
}
.sticky-footer {
  position: sticky;
  bottom: 0;
}
```

The drag then treats the part of the container between them as the container:

- With `constrainToContainer`, the preview stays between the header and the footer.
- Auto-scroll starts at the header's lower edge and the footer's upper edge. A pointer over either scrolls at full speed.
- The pointer over the header or footer is not over the list, as outside the container. The drop position still follows the preview's top edge, as at any edge of the container, so without `constrainToContainer` a preview pulled over the header can point at a row behind it.
- A keyboard drag scrolls the list to keep the placeholder between the header and the footer.
- A list in a scroll container nested inside this one is treated the same way where it scrolls under the header or footer: it is not targeted there, auto-scroll over them scrolls the outer container, and its constrained preview and keyboard placeholder stay clear of them.

When the header collapses or grows while the page scrolls, keep the height you pass up to date: a drag in progress measures again when it changes, and a keyboard drag scrolls its placeholder clear of them again.

Measure the insets from the container's outer (border) edges: a border on the container adds its width, and a horizontal scrollbar under a `bottom: 0` footer adds its height.

`<vdnd-sortable-list>`, `<vdnd-virtual-scroll>` and `<vdnd-virtual-viewport>` take the same inputs for content overlaid on their own rows, such as a header positioned over the top of the list. They also leave that space around their rows: the first row starts below the top inset, and the list scrolls far enough for the last row to clear the bottom one. In `<vdnd-virtual-viewport>`, the rows start `contentOffset` down when that is more than the top inset.

## Ionic

`<ion-content>` scrolls an element inside its shadow DOM, so `vdndScrollable` cannot go on `ion-content` itself. Turn off its scrolling and add a scroll host in the light DOM:

```angular-html
<ion-content [scrollY]="false">
  <div class="ion-content-scroll-host" vdndScrollable>
    <!-- vdndGroup, vdnd-virtual-content, footer... -->
  </div>
</ion-content>
```

```css
.ion-content-scroll-host {
  height: 100%;
  overflow-y: auto;
}
```

The [page scroll demo](https://gultyayev.github.io/ngx-virtual-dnd/demo/page-scroll) is a complete Ionic task manager built this way.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Drag behavior

These inputs change when a drag starts and how it moves. All of them are optional.

Only one drag runs at a time. While an item is being dragged, with the pointer or the keyboard, pressing another item (a second finger on a touch screen) or pressing Space
 on it does not start a second drag.
## Drag handles

Set `dragHandle` to a CSS selector, and only presses inside a matching element in the row start a drag (an element around the row that matches doesn't count). The rest of the row stays free for selecting text, clicking and so on.


Live exampleList with drag handles[Open in new tab](/ngx-virtual-dnd/demo/examples/drag-handle/)

```ts file="<root>/src/app/examples/drag-handle/drag-handle.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  reorderItems,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Track {
  id: string;
  title: string;
}

@Component({
  selector: 'app-drag-handle-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  template: `
    <div vdndGroup="playlist">
      <ng-template #trackTpl let-track>
        <!-- Only presses inside [data-drag-handle] start a drag; the rest of the row stays selectable -->
        <div class="row with-handle" [vdndDraggable]="track.id" dragHandle="[data-drag-handle]">
          <span class="handle" data-drag-handle aria-hidden="true">
            <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
              <circle cx="9" cy="6" r="1.6" />
              <circle cx="15" cy="6" r="1.6" />
              <circle cx="9" cy="12" r="1.6" />
              <circle cx="15" cy="12" r="1.6" />
              <circle cx="9" cy="18" r="1.6" />
              <circle cx="15" cy="18" r="1.6" />
            </svg>
          </span>
          <span>{{ track.title }}</span>
        </div>
      </ng-template>

      <vdnd-sortable-list
        class="list"
        droppableId="playlist"
        [items]="tracks()"
        [itemHeight]="48"
        [containerHeight]="336"
        [itemIdFn]="trackId"
        [itemTemplate]="trackTpl"
        (drop)="onDrop($event)"
      />
    </div>

    <vdnd-drag-preview />
  `,
})
export class DragHandleExampleComponent {
  readonly tracks = signal<Track[]>(
    Array.from({ length: 300 }, (_, i) => ({ id: `track-${i + 1}`, title: `Track ${i + 1}` })),
  );

  readonly trackId = (track: Track): string => track.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tracks);
  }
}

```

Make the handle a non-interactive element such as a `<span>`. Presses inside a button in the row never start a drag, as the next section explains. Keyboard dragging is unaffected: the whole row stays focusable.

## Interactive children

Controls inside rows keep working: pressing them never starts a drag. What starts a drag depends on where the pointer press lands, or on which element has focus when Space
 is pressed:
| Element                                                                                                     | Pointer press starts a drag               | <kbd>Space</kbd> while it has focus picks the row up                                              |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| The row itself, even when the draggable element is a button, such as `<button vdndDraggable>`               | Yes                                       | Yes                                                                                               |
| The row, when the draggable element is another control, such as an `input` or a `[contenteditable]` element | No, except from a drag handle (see below) | No: it types, toggles or opens instead. A focusable drag handle inside it can                     |
| A row inside a control, such as the blocks of a `[contenteditable]` editor                                  | Yes                                       | Not in Chromium (see below)                                                                       |
| The row outside the handle, when `dragHandle` is set                                                        | No                                        | Yes, unless the draggable element is a text field, `select` or editable element                   |
| A non-interactive [drag handle](#drag-handles), such as a `<span>`                                          | Yes                                       | Yes, when you make it focusable (`tabindex="0"`); otherwise it cannot take focus, and the row can |
| A drag handle that is a `button`                                                                            | No                                        | Yes                                                                                               |
| A `button`, `input`, `textarea`, `select` or `[contenteditable]` element inside the row                     | No                                        | No: it types or clicks instead                                                                    |
| An element with the `no-drag` class, and everything inside it                                               | No                                        | No                                                                                                |
| The row, with `no-drag` on the draggable element itself                                                     | No                                        | Yes                                                                                               |

Only controls inside the row count: a control around the list doesn't stop a drag, and neither does a draggable element that is a button (a `button`
, or an `input`
 of type `button`
, `submit`
, `reset`
 or `image`
). A draggable element that is another control, such as a text field, a checkbox, a `select`
 or a `[contenteditable]`
 element, keeps its own press and Space
: a press focuses, opens, toggles or places the caret, and Space
 types a space, toggles or opens. An element with `contenteditable="false"`
 is not editable, so it doesn't count either.
Rows inside a `[contenteditable]`
 editor drag like any other row, so pressing one starts a drag instead of placing the caret. To keep their text editable with the mouse, give them a [drag handle](#drag-handles)
. The same goes for blocks that are their own editing host (`<div contenteditable vdndDraggable>`
): give them a handle with `contenteditable="false"`
, such as a grip icon, and presses on it start a drag while the rest of the block stays editable. Space
 in the block's text types a space, so make the grip focusable for keyboard users, with `tabindex="0"`
, `role="button"`
 and an `aria-label`
 such as "Drag block": Space
 on it picks the block up. Without a focusable handle, the block can't be moved with the keyboard. After a keyboard drop or cancel, focus returns to the block itself (placing the caret in it), so Tab
 reaches the grip again. In Chromium, Space
 on a row inside an editor goes to the editor instead of picking the row up; Firefox and Safari pick it up.
Only the primary mouse button starts a drag. To turn dragging off completely, use [`disabled`](#disabling).

Other interactive elements are not recognized, for example a web component whose input is inside its shadow DOM, or an element with `role="switch"`. Add `no-drag` to them. For a web component, add it to the component element itself: presses inside its shadow DOM reach the row as presses on that element.

## Threshold and delay

```angular-html
<div [vdndDraggable]="task.id" [dragThreshold]="10" [dragDelay]="200">{{ task.title }}</div>
```

| Input           | Default | Effect                                                                                                                                                   |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dragThreshold` | `5`     | How far (px) the pointer must move before the drag starts. Stops clicks from turning into drags.                                                         |
| `dragDelay`     | `0`     | How long (ms) the pointer must be held first. Moving past the threshold before the delay ends cancels the drag attempt, so touch users can still scroll. |

When the delay has passed, the element gets the `vdnd-drag-pending` class. Style it so users can see the item is ready to move:

```css
.vdnd-drag-pending {
  transform: scale(1.02);
  box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
}
```

A delay of 150–250 ms works well on touch devices.

## Axis locking

```angular-html
<div [vdndDraggable]="task.id" lockAxis="x">{{ task.title }}</div>
```

`lockAxis` names the axis that is **frozen**:

- `'x'`: the X axis is frozen, so the item moves only vertically
- `'y'`: the Y axis is frozen, so the item moves only horizontally

:::warning Migrating from Angular CDK
This is the opposite of CDK's `cdkDragLockAxis`, where `'x'` means the item moves along the X axis.
:::

## Constraining to the container

```angular-html
<vdnd-sortable-list [constrainToContainer]="true" ... />
<!-- or -->
<div vdndDroppable="tasks" [constrainToContainer]="true">...</div>
```

The preview cannot leave the container. Holding it against the container's top or bottom edge drops the item at the first or last position once the list is scrolled to that end; until then the drop position is the visible row at that edge, while autoscroll, when it runs, moves the list there. The container is the nearest `vdndScrollable` ancestor if there is one, and the droppable otherwise.

When a sticky header or footer inside the `vdndScrollable` element covers part of it, pass their heights as `scrollInsetTop` and `scrollInsetBottom` so the preview stays clear of them (see [Sticky headers and footers](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md#sticky-headers-and-footers)).

## Disabling

Every draggable, droppable and list accepts `disabled`:

```angular-html
<div [vdndDraggable]="task.id" [disabled]="task.locked">{{ task.title }}</div>

<!-- Nothing can be dropped into this list -->
<vdnd-sortable-list [disabled]="locked()" ... />
```

- A **disabled draggable** cannot be picked up. It gets `tabindex="-1"` and the `vdnd-draggable-disabled` class.
- A **disabled droppable** (or `<vdnd-sortable-list>`) is skipped as a target. Its items can still be dragged out, so for a read-only list also disable the draggables in its item template. The pointer passes through to whatever enabled droppable is underneath, and keyboard left/right navigation skips it. Releasing over it emits no `(drop)`. `(dragEnd)` still fires with `destinationIndex: null`. It gets the `vdnd-droppable-disabled` class.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/auto-scroll.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Auto-scroll

While an item is dragged near the edge of a scrollable list, the list scrolls toward that edge. The closer the pointer is to the edge, the faster it scrolls. Auto-scroll is on by default.

```angular-html
<vdnd-sortable-list [autoScrollConfig]="{ threshold: 80, maxSpeed: 20 }" ... />
```

| Option       | Default | Meaning                                                  |
| ------------ | ------- | -------------------------------------------------------- |
| `threshold`  | `50`    | Distance from the edge, in px, at which scrolling starts |
| `maxSpeed`   | `15`    | Maximum speed, in px per frame at 60 fps                 |
| `accelerate` | `true`  | Scroll faster the closer the pointer is to the edge      |

`autoScrollConfig` accepts a partial object. Options you leave out keep their defaults.

## Where it applies

`autoScrollEnabled` and `autoScrollConfig` exist on every scroll container:

- `<vdnd-sortable-list>`
- `<vdnd-virtual-scroll>`
- `<vdnd-virtual-viewport>`
- `vdndDroppable`
- `vdndScrollable` (page-level and external scroll containers)

When scroll containers are nested, auto-scroll starts with the innermost container under the pointer. Once that container reaches its end, it moves on to the outer one.

## Disabling

```angular-html
<vdnd-sortable-list [autoScrollEnabled]="false" ... />
```



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Preview and placeholder

During a drag the original element is hidden. Two elements take its place:

- the **preview**, which follows the pointer
- the **placeholder**, an empty slot that marks where the item will land

## Default preview

`<vdnd-drag-preview />` clones the dragged element, copies its computed styles and sizes the clone to match the original. The point where the user grabbed the item stays under the pointer.

The clone is a picture of the item: its controls are disabled and out of the tab order. It keeps the item's `id` attributes, so rules that style the item through an ID style the clone too. That means the document has each of those IDs twice during a drag; see [Known limitations](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md#drag-preview).

The clone is made in the frame the item lifts, and copying the styles takes longer the more elements the row has. For rows with many elements on low-end devices, a [custom preview](#custom-preview) is cheaper: with a template, drags skip the clone.

## Custom preview

Pass a template to render your own preview instead of a clone:


Live exampleList with a custom drag preview[Open in new tab](/ngx-virtual-dnd/demo/examples/custom-preview/)

```ts file="<root>/src/app/examples/custom-preview/custom-preview.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  reorderItems,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Task {
  id: string;
  title: string;
}

@Component({
  selector: 'app-custom-preview-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  template: `
    <div vdndGroup="tasks">
      <ng-template #taskTpl let-task>
        <!-- vdndDraggableData is what the preview template receives -->
        <div class="row" [vdndDraggable]="task.id" [vdndDraggableData]="task">
          {{ task.title }}
        </div>
      </ng-template>

      <vdnd-sortable-list
        class="list"
        droppableId="tasks"
        [items]="tasks()"
        [itemHeight]="48"
        [containerHeight]="336"
        [itemIdFn]="taskId"
        [itemTemplate]="taskTpl"
        (drop)="onDrop($event)"
      />
    </div>

    <!-- Rendered instead of a clone of the row. Style it globally: it lives under <body> -->
    <ng-template #preview let-task>
      <div class="preview-card">
        Moving <strong>{{ task.title }}</strong>
      </div>
    </ng-template>

    <vdnd-drag-preview [previewTemplate]="preview" />
  `,
})
export class CustomPreviewExampleComponent {
  readonly tasks = signal<Task[]>(
    Array.from({ length: 1000 }, (_, i) => ({ id: `task-${i + 1}`, title: `Task ${i + 1}` })),
  );

  readonly taskId = (task: Task): string => task.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tasks);
  }
}

```

The template context:

| Variable      | Value                                                   |
| ------------- | ------------------------------------------------------- |
| `$implicit`   | The draggable's `vdndDraggableData` (`null` if not set) |
| `draggableId` | ID of the dragged item                                  |
| `droppableId` | ID of the droppable the drag started in                 |

Set `[vdndDraggableData]="task"` on the draggable so the template receives the item.

:::warning The preview lives under `<body>`
The preview is moved into a `div.vdnd-overlay-container` at the end of `<body>`. This escapes ancestor `transform`, `filter` and `perspective` styles, which would otherwise break `position: fixed` (Ionic's `ion-page` is one example). Your component's styles still apply to elements in the preview template. But selectors that depend on ancestors, such as `.board .card`, no longer match. Style the preview by its own classes.
:::

The preview box is `inert` and `aria-hidden="true"`, with a default or a custom preview alike: nothing in it takes focus or reaches screen readers. Announce the drag yourself (see [Accessibility](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md)), not with live content in the preview template.

`cursorOffset` (default `{ x: 8, y: 8 }`) is only a fallback for when the grab point is unknown. Drags started by the library always know it.

## Placeholder

Lists render the placeholder at the drop position, sized to the dragged item. It is an empty element with the classes `vdnd-drag-placeholder` and `vdnd-drag-placeholder-visible`. Style it globally:

```css
.vdnd-drag-placeholder {
  box-sizing: border-box;
  border: 2px dashed #9aa4b2;
  border-radius: 8px;
}
```

`<vdnd-placeholder>` (`PlaceholderComponent`) is a separate indicator that accepts a custom template and that you render yourself. The built-in lists do not use it.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Animations and haptics

By default, rows displaced by the placeholder jump to their new position, and the preview disappears on drop. Provide `VDND_ANIMATION_CONFIG` to make rows slide and the dropped item glide into its slot instead. For feedback on every step, such as a haptic tick, listen to `(placeholderMove)`.


Live exampleSliding rows and a placeholder move counter[Open in new tab](/ngx-virtual-dnd/demo/examples/shift-animation/)

```ts file="<root>/src/app/examples/shift-animation/shift-animation.ts"
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  DragPreviewComponent,
  DraggableDirective,
  DropEvent,
  DroppableGroupDirective,
  PlaceholderMoveEvent,
  reorderItems,
  VDND_ANIMATION_CONFIG,
  VirtualSortableListComponent,
} from 'ngx-virtual-dnd';

interface Task {
  id: string;
  title: string;
}

@Component({
  selector: 'app-shift-animation-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    VirtualSortableListComponent,
    DroppableGroupDirective,
    DraggableDirective,
    DragPreviewComponent,
  ],
  // Lists in this component slide displaced rows instead of snapping them into place
  providers: [{ provide: VDND_ANIMATION_CONFIG, useValue: { shiftDuration: 200 } }],
  template: `
    <p class="status">
      Placeholder moves: <strong data-placeholder-moves>{{ moves() }}</strong>
      @if (lastMove()) {
        · last <strong data-last-placeholder-move>{{ lastMove() }}</strong>
      }
    </p>

    <div vdndGroup="tasks">
      <ng-template #taskTpl let-task>
        <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
      </ng-template>

      <vdnd-sortable-list
        class="list"
        droppableId="tasks"
        [items]="tasks()"
        [itemHeight]="48"
        [containerHeight]="288"
        [itemIdFn]="taskId"
        [itemTemplate]="taskTpl"
        (drop)="onDrop($event)"
        (placeholderMove)="onPlaceholderMove($event)"
      />
    </div>

    <vdnd-drag-preview />
  `,
})
export class ShiftAnimationExampleComponent {
  readonly tasks = signal<Task[]>(
    Array.from({ length: 500 }, (_, i) => ({ id: `task-${i + 1}`, title: `Task ${i + 1}` })),
  );

  readonly moves = signal(0);
  readonly lastMove = signal('');

  readonly taskId = (task: Task): string => task.id;

  onPlaceholderMove(event: PlaceholderMoveEvent): void {
    // One event per displacement: a good place for haptic feedback
    navigator.vibrate?.(10);
    this.moves.update((count) => count + 1);
    this.lastMove.set(`${event.previousIndex ?? 'entered'} → ${event.currentIndex}`);
  }

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tasks);
  }
}

```

## Shift animation

The animation is opt-in. Provide the config app-wide, or in a component's `providers` to animate only the lists in that subtree:

```ts
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { VDND_ANIMATION_CONFIG } from 'ngx-virtual-dnd';

export const appConfig: ApplicationConfig = {
  providers: [{ provide: VDND_ANIMATION_CONFIG, useValue: { shiftDuration: 200 } }],
};
```

| Option          | Default                      | Meaning                                                            |
| --------------- | ---------------------------- | ------------------------------------------------------------------ |
| `shiftDuration` | `200`                        | Slide duration in ms. `0` turns it off                             |
| `shiftEasing`   | `cubic-bezier(0.2, 0, 0, 1)` | Any CSS easing function                                            |
| `dropDuration`  | `200`                        | [Drop animation](#drop-animation) duration in ms. `0` turns it off |
| `dropEasing`    | `cubic-bezier(0.2, 0, 0, 1)` | Any CSS easing function                                            |

- The slide animates the `translate` CSS property, so it runs on the compositor. It works with virtual scrolling and with [dynamic heights](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md).
- It is skipped when the user has turned on reduced motion (`prefers-reduced-motion: reduce`).
- If the placeholder moves again mid-slide, rows continue from where they currently are.
- Drop positions are calculated from geometry, so a row that is still sliding never changes where an item lands.
- Rows also slide on drop or cancel. After a drop they usually already sit in their final slots, so a slide in progress simply finishes. After a cancel, displaced rows slide back.
- Your own `transform` on rows is kept: the slide moves the row as a whole, and your rotation or scale does not distort the slide. If you set `translate` on rows yourself, the slide is added to it, but then it runs on the main thread instead of the compositor, so prefer `transform` for your own offsets. A `translate` you change while a row is sliding applies once the slide ends.

The config is read each time an animation starts, so a getter can switch it at runtime, for example from a user setting:

```ts
{
  provide: VDND_ANIMATION_CONFIG,
  useFactory: () => {
    const settings = inject(SettingsService);
    return {
      get shiftDuration() {
        return settings.reduceAnimations() ? 0 : 200;
      },
    };
  },
}
```

## Drop animation

With the same config, releasing an item no longer makes the preview vanish. The preview glides from where you let go onto the item's final position, then disappears. The real item stays invisible until the preview lands on it, so it is never shown twice. A cancelled drag (Escape
) glides back to where the item started.
- It is purely visual. `drop` and `dragEnd` fire right away, and the list is already in its new order while the preview travels.
- The preview lands on the item as it is rendered after your `(drop)` handler. Commit the move in the handler (for example with `moveItem()` or `reorderItems()`). If you commit later, for example after a server call, the preview glides back to the item's old slot.
- If the item is not rendered, or is scrolled out of its list's view, the preview fades out where it was released.
- Starting a new drag ends the animation at once.
- While it plays, the preview box has the class `vdnd-drag-preview-dropping`.
- It is skipped under reduced motion, like the shift animation. Set `dropDuration: 0` to keep only the shift animation.

### Where it applies

Rows animate in `<vdnd-sortable-list>`, `<vdnd-virtual-scroll>` and every `*vdndVirtualFor` list, including those inside `<vdnd-virtual-viewport>` and `<vdnd-virtual-content>`.

:::warning
Do not add your own CSS `transition` on the rows' `transform`, `translate` or `top` to get this effect. Rows are repositioned by layout (or by an inline `top` in a `*vdndVirtualFor` placed directly in a `vdndScrollable`), and a transition on any of them competes with the built-in slide.
:::

## Placeholder move events

`vdndDroppable` and `<vdnd-sortable-list>` emit `placeholderMove` each time the placeholder moves within that list, which is every time rows are displaced:

```angular-html
<vdnd-sortable-list ... (placeholderMove)="onPlaceholderMove($event)" />
```

```ts
onPlaceholderMove(event: PlaceholderMoveEvent): void {
  navigator.vibrate?.(10); // or Haptics.selectionChanged() from @capacitor/haptics
}
```

The event fires when the placeholder enters the list and on every move inside it. It does not fire for the initial pick-up or when the placeholder leaves the list. `currentIndex` is where the item would land if it were dropped now, so it also suits [screen reader announcements](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md#screen-reader-announcements). See [`PlaceholderMoveEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#placeholdermoveevent) for every field.

Keep the handler cheap, and bind it only where you use it: each event runs change detection for your component and its ancestors (see [Performance](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md#placeholder-move-listeners)).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/styling.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Styling

The library ships no visual styles for items, lists or the drop placeholder. It adds state classes, listed below, that you style however you like.

Put the rules below in a global stylesheet (`styles.css`, or a component with `ViewEncapsulation.None`). The library renders the preview, the placeholder and the lists' inner elements, so your component's scoped styles do not reach them. Styles for your own row elements can stay in the component that declares the row template.

## Classes

| Class                                                    | On                                  | When                                                 |
| -------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------- |
| `vdnd-draggable`                                         | Draggables                          | Always                                               |
| `vdnd-draggable-dragging`                                | Draggables                          | While being dragged (the element is `display: none`) |
| `vdnd-draggable-disabled`                                | Draggables                          | `disabled` is true                                   |
| `vdnd-drag-pending`                                      | Draggables                          | `dragDelay` has passed, drag not started yet         |
| `vdnd-droppable`                                         | Droppables                          | Always                                               |
| `vdnd-droppable-active`                                  | Droppables                          | The pointer or keyboard target is this droppable     |
| `vdnd-droppable-disabled`                                | Droppables                          | `disabled` is true                                   |
| `vdnd-drag-placeholder`, `vdnd-drag-placeholder-visible` | Drop-position placeholder           | During a drag, in the target list                    |
| `vdnd-drag-preview`                                      | Preview box                         | During a drag                                        |
| `vdnd-drag-preview-dropping`                             | Preview box                         | While it plays the drop animation                    |
| `vdnd-overlay-container`                                 | Body-level container of the preview | After `<vdnd-drag-preview>` renders                  |
| `vdnd-dragging`                                          | `<body>`                            | While any drag is in progress                        |
| `vdnd-dragging-touch`                                    | `<body>`                            | While a touch drag is in progress                    |

`<vdnd-sortable-list>`, `<vdnd-virtual-scroll>`, `<vdnd-virtual-viewport>`, `<vdnd-virtual-content>`, `vdndScrollable` and `<vdnd-placeholder>` also carry their own name as a class (for example `vdnd-sortable-list`).

## Recipes

Show where the item will land:

```css
.vdnd-drag-placeholder {
  box-sizing: border-box;
  border: 2px dashed #9aa4b2;
  border-radius: 8px;
}
```

Highlight the list under the pointer. With `<vdnd-sortable-list>` the droppable is an inner element, so target it through the list:

```css
.vdnd-sortable-list .vdnd-droppable-active {
  background: #e4f3f2;
  box-shadow: inset 0 0 0 2px #0e9488;
}
```

Give the preview some lift:

```css
.vdnd-drag-preview > * {
  border-radius: 12px;
  box-shadow: 0 18px 40px -18px rgb(20 28 46 / 0.3);
  transform: rotate(1.5deg);
}
```

Dim items that cannot be dragged:

```css
.vdnd-draggable-disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
```

Show a grab cursor on hover, and stop hover styles from firing on other rows during a drag:

```css
.vdnd-draggable {
  cursor: grab;
}

body.vdnd-dragging .vdnd-draggable {
  pointer-events: none;
}
```

## The built-in cursor

The library's only built-in style is a `grabbing` cursor over lists and items (`vdnd-droppable` and `vdnd-draggable` elements) during mouse and keyboard drags. Touch drags get no cursor. The rest of the page keeps its cursor, and so do elements inside items and lists that set their own `cursor` (a drag handle with `cursor: grab`, a button); the `pointer-events: none` recipe above covers those inside items.

Show the grabbing cursor over the whole page during a drag, not only over lists and items. A rule on `body` alone is enough, because `cursor` inherits; it costs a style recalculation that grows with the size of the page each time a drag starts and ends. Avoid `body.vdnd-dragging *`, which restyles every element:

```css
body.vdnd-dragging:not(.vdnd-dragging-touch) {
  cursor: grabbing;
}
```



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Accessibility

Every draggable can be moved with the keyboard, with nothing to enable. The exception is an item that is itself a text field, a `select`, a checkbox or an editable element, which needs a focusable drag handle (see below).

## Keyboard

| Key                       | Not dragging                                                                                                       | During a keyboard drag                                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| <kbd>Tab</kbd>            | Moves focus between draggables                                                                                     | Cancels the drag                                                                                                |
| <kbd>Space</kbd>          | Picks up the focused item (except in an item that is itself a text field, `select` or editable element; see below) | Drops                                                                                                           |
| <kbd>Enter</kbd>          | —                                                                                                                  | Drops                                                                                                           |
| <kbd>↑</kbd> <kbd>↓</kbd> | —                                                                                                                  | Moves the target position                                                                                       |
| <kbd>←</kbd> <kbd>→</kbd> | —                                                                                                                  | Moves to the neighbouring list in the same group, by on-screen position (disabled and hidden lists are skipped) |
| <kbd>Escape</kbd>         | —                                                                                                                  | Cancels. Also cancels pointer drags.                                                                            |

A hidden list is one that is still in the page but not shown: `display: none` on it or an ancestor (an inactive tab, a column hidden by a media query), `visibility: hidden`, or a size of zero. Pointer drags skip hidden lists too: the drag falls through to the list underneath, if any, as it does for a disabled list.

Pressing Space
 in a control inside an item, such as a text field or a button, types into or clicks that control and does not pick the item up, unless the control is the drag handle. The same goes for an item that is itself a text field, `textarea`
, `select`
, checkbox or editable element: Space
 types into it, toggles it or opens it, and only Space
 on a focusable drag handle inside it picks it up (see [Interactive children](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#interactive-children)
). So such an item needs one:
- An `input`, `textarea` or `select` can't hold a handle. Make a row element the draggable instead and put the control inside it.
- A `[contenteditable]` draggable without a focusable handle can't be moved with the keyboard. Give it a handle such as `<span class="grip" contenteditable="false" tabindex="0" role="button" aria-label="Drag block">`.

After a keyboard drop or cancel, focus returns to the draggable element itself. For an editable block that puts the caret in the block; press Tab
 to reach a grip inside it again.
Moving past the edge of the visible area scrolls the list to show where the item will land, so the keyboard reaches every item, not just the rendered ones. A list of plain `@for` rows scrolls the containers around it, nearest first.

## Managed for you

- `tabindex="0"` on draggables (`-1` when disabled)
- After a keyboard drag, focus returns to the moved item in its new position
- `aria-grabbed` on draggables and `aria-dropeffect="move"` on droppables

`aria-grabbed` and `aria-dropeffect` are deprecated since ARIA 1.1, and most screen readers ignore them. They do not tell screen reader users that an item can be dragged, how to drag it, or where it is. Add instructions and announcements yourself, as described below.

## Instructions

Nothing tells a screen reader user that Space
 picks an item up. Describe the keys once in a hidden element and point every draggable at it with `aria-describedby`
. Screen readers read the description when the item gets focus:
```angular-html
<p id="drag-instructions" hidden>
  Press Space to pick up. Use the arrow keys to move, Space to drop and Escape to cancel.
</p>

<ng-template #taskTpl let-task>
  <div [vdndDraggable]="task.id" aria-describedby="drag-instructions">{{ task.title }}</div>
</ng-template>
```

## Screen reader announcements

The library does not make announcements itself, so wording and translations stay in your hands. The events carry everything you need: `(dragStart)` for the pick-up, `(placeholderMove)` for every step and `(dragEnd)` for the result. Render the messages in a live region:

```ts
@Component({
  template: `
    <p id="drag-instructions" hidden>
      Press Space to pick up. Use the arrow keys to move, Space to drop and Escape to cancel.
    </p>

    <div vdndGroup="tasks">
      <ng-template #taskTpl let-task>
        <div
          [vdndDraggable]="task.id"
          [vdndDraggableData]="task"
          aria-describedby="drag-instructions"
          (dragStart)="onDragStart($event)"
          (dragEnd)="onDragEnd($event)"
        >
          {{ task.title }}
        </div>
      </ng-template>

      <vdnd-sortable-list
        droppableId="tasks"
        [items]="tasks()"
        [itemHeight]="48"
        [containerHeight]="400"
        [itemIdFn]="taskId"
        [itemTemplate]="taskTpl"
        (drop)="onDrop($event)"
        (placeholderMove)="onPlaceholderMove($event)"
      />
    </div>

    <div class="sr-only" aria-live="assertive">{{ announcement() }}</div>
  `,
})
export class TasksComponent {
  readonly #dragState = inject(DragStateService);
  readonly announcement = signal('');

  onDragStart(event: DragStartEvent): void {
    const task = event.data as Task;
    this.announcement.set(
      `Picked up ${task.title}, position ${event.sourceIndex + 1} of ${this.tasks().length}`,
    );
  }

  onPlaceholderMove(event: PlaceholderMoveEvent): void {
    // Pointer users see the placeholder move; announce keyboard steps only
    if (!this.#dragState.isKeyboardDrag()) return;
    this.announcement.set(`Position ${event.currentIndex + 1} of ${this.tasks().length}`);
  }

  onDragEnd(event: DragEndEvent): void {
    this.announcement.set(
      event.destinationIndex === null
        ? `Cancelled. Back at position ${event.sourceIndex + 1}`
        : `Dropped at position ${event.destinationIndex + 1}`,
    );
  }

  // tasks, taskId and onDrop as in the Quick start
}
```

`.sr-only` is the usual visually-hidden utility (`position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%);`).

With [multiple lists](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md), also name the list in the step message: `event.droppableId` is the list the placeholder is in.

## Touch

Touch drags work out of the box. If your lists also need to scroll by touch, add a short [`dragDelay`](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md#threshold-and-delay) so a quick swipe scrolls and a press-and-hold drags.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Performance

Virtual scrolling keeps the DOM small however long the list grows, so most apps need no tuning. This page collects the settings that matter when rows are costly to render or devices are slow.

## Row recycling

By default, `<vdnd-sortable-list>` and `<vdnd-virtual-scroll>` create a row's view (its elements, components and directives) when the row scrolls into range, and destroy it when the row scrolls out. With `[recycleRows]="true"` they keep the views of the rows that scroll out and render the rows that scroll in with them, so scrolling creates few components and elements. `*vdndVirtualFor` always recycles rows.

A recycled view renders another item, and keeps whatever does not come from its bindings:

- **Components in the row are not created again.** Their constructor and `ngOnInit` run once, for the first item the view renders; later items only change their inputs. Derive what a row shows from its inputs (`input()`, `computed()`), not from values read once in `ngOnInit`.
- **Local state stays with the view.** A component's own fields and signals, and the value of an input field that is not bound to the item, show up on the next item.
- **DOM state that no binding sets stays**: classes or styles set from code, an element's scroll position, an `<img>` until its new `src` loads.

Focus does not carry over: a view leaves the DOM before it renders another item. A row keeps its view while its item stays rendered, as without recycling.

A row with a leave animation (`animate.leave`) on its root element is not recycled, by `*vdndVirtualFor` either, even when its bound value is empty: Angular keeps the row in the DOM until the leave animation has run. On Angular 22 this also applies to `animate.leave` on any element inside the row. See [Animations on rows that move](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md#animations-on-rows-that-move).

Turn it on for rows that are costly to create (several components, many elements) and render only from their item.

## Overscan

`overscan` is the number of rows rendered beyond the visible area, above and below. The default is `3`. Raise it if fast scrolling shows empty space before rows appear. Lower it when rows are costly to render.

```angular-html
<vdnd-sortable-list [overscan]="5" ... />

<ng-container *vdndVirtualFor="let task of tasks(); trackBy: trackById; overscan: 5">...</ng-container>
```

`<vdnd-sortable-list>`, `<vdnd-virtual-scroll>` and `*vdndVirtualFor` accept it.

## Fixed or dynamic heights

Fixed heights cost nothing to measure: every offset is `index * itemHeight`. [`dynamicItemHeight`](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/dynamic-heights.md) observes every rendered row with a `ResizeObserver`. Turn it on only when rows really differ in height.

## The drag preview

The default preview clones the dragged row and copies its computed styles, in the frame the item lifts. That takes longer the more elements the row has. For rows with many elements, a [custom preview template](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md#custom-preview) is cheaper: with a template, drags skip the clone.

## Placeholder move listeners

Like any Angular template listener, `(placeholderMove)` marks your component and its ancestors for check each time it fires, which can be many times per second during a drag. Bind it only where you use it, and keep the handler cheap. See [Placeholder move events](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md#placeholder-move-events).

## Global styles during a drag

The library adds `vdnd-dragging` to `<body>` at drag start and removes it at drop. A rule such as `body.vdnd-dragging *` restyles every element on the page both times. Target the elements you need instead; see [The built-in cursor](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/styling.md#the-built-in-cursor).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/more/faq.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# FAQ

## Which Angular versions are supported?

Angular 21 and 22. See [Installation](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/installation.md#requirements).

## Does it work in zoneless apps? And with zone.js?

Both. Drag state lives in signals, so zoneless apps need nothing extra; the live examples in these docs are zoneless. In zone.js apps, `dragStart`, `dragEnd` and `drop` are emitted inside the zone, so handlers that change plain fields still render.

## Does it work with server-side rendering?

Yes. On the server, the lists render their first rows without errors and without a browser `document`, and drag and drop starts once the app runs in the browser. With `provideClientHydration()`, the browser keeps the rows the server rendered instead of creating them again. The library's tests render every list component with Angular's server renderer, and hydrate it in a browser DOM.

## Can lists in different components exchange items?

Yes. Groups are matched by name, so two `vdndGroup="board"` elements in different components form one group. Each component declares its item template inside its own `vdndGroup` element, and draggable IDs must still be unique across all lists.

Only the destination list emits `(drop)`, so the component of the source list does not hear about the move. Keep the lists' data in a shared service or store and apply the move there, for example with [`applyMove()`](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md#stores-and-immutable-state).

## Can a list accept only some items?

Yes, by disabling it while an item it rejects is dragged. See [Accepting only some items](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md#accepting-only-some-items).

## Can I reorder horizontally, or in a grid?

No. Lists are vertical; a board of side-by-side vertical columns works. See [Known limitations](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md#scope).

## How do I save the new order to a server?

Apply the move in `(drop)` straight away, send the request, and roll back if it fails. See [Saving to a server](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md#saving-to-a-server).

## Does it work with Ionic?

Yes, including lists that scroll with `ion-content`. See [Page-level scrolling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md#ionic).

## How do I test drag and drop in my app?

**Unit-test the drop handler.** It only maps a `DropEvent` to new data, so call it with an event object:

```ts
it('moves a task to "done"', () => {
  component.onDrop({
    source: { draggableId: 'task-1', droppableId: 'todo', index: 0 },
    // placeholderId is deprecated, but the type requires it until the next major version
    destination: { droppableId: 'done', placeholderId: 'END_OF_LIST', index: 0 },
  });

  expect(component.done()[0].id).toBe('task-1');
});
```

**Test the drag itself in a real browser**, with Playwright or Cypress. Hit-testing works from element positions, and jsdom (used by Jest) has no layout, so drags cannot be simulated there.

- The library sets `data-draggable-id` and `data-droppable-id` to their IDs. Use them to find items and lists.
- A virtual list renders only the rows in view. Scroll a row into view before you look for it.
- Keyboard drags need no coordinates, which makes them the simplest to script:

```ts
await page.locator('[data-draggable-id="task-1"]').focus();
await page.keyboard.press('Space');
await expect(page.locator('.vdnd-drag-preview')).toBeVisible();
await page.keyboard.press('ArrowDown');
await page.keyboard.press('Space');
```

- For a pointer drag, press on the item, move past the drag threshold (5 px by default), wait for `.vdnd-drag-preview` to appear, then move to the target in several steps and release. A single jump straight to the target can be released before the library has processed the new position.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/more/troubleshooting.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Troubleshooting

Most problems come from one of the [rules that fail silently](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md#rules-that-fail-silently). Run the app in dev mode first: several of them log a console warning there.

| Symptom                                                                          | Likely cause and fix                                                                                                                                              |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing drags; the console mentions a missing group                              | No group resolved. Add `vdndGroup` and declare the item template inside it.                                                                                       |
| The list area is empty or 0 px tall                                              | The list has no height. Set `containerHeight` or a CSS height on the scrolling element.                                                                           |
| Dragging works, but nothing follows the pointer                                  | `<vdnd-drag-preview />` is missing.                                                                                                                               |
| The drag cancels when the item scrolls out of view, or dynamic heights are wrong | The `vdndDraggable` ID differs from `itemIdFn` / `trackBy`. Use the same string in both places.                                                                   |
| Drops land a row or more off, worse further down the list                        | Rows are not exactly `itemHeight` tall. Fix the row height (borders and padding included) or turn on `dynamicItemHeight`.                                         |
| Items in other lists disappear while dragging                                    | Draggable IDs are duplicated across lists. Make them unique app-wide.                                                                                             |
| Items cannot be dropped into another list                                        | The lists are in different groups, or the target list has no `(drop)` handler.                                                                                    |
| `(drop)` fires but the arrays do not change                                      | The keys passed to `moveItem()` do not match the `droppableId`s.                                                                                                  |
| A gap stays where the dragged item was                                           | `vdndDraggable` is on a nested element. Move it to the template's root element.                                                                                   |
| A custom control inside a row starts a drag instead of responding                | Native buttons and inputs are already excluded. For other controls, add the `no-drag` class to the control (it covers everything inside it), or use `dragHandle`. |
| The preview loses its styling                                                    | The styles rely on ancestor selectors, and the preview is rendered under `<body>`. Target the preview's own classes.                                              |
| Drops land in the wrong list where two lists overlap                             | Hit-testing is geometric. See [Known limitations](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md#hit-testing).                             |

Still stuck? Check the [FAQ](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/faq.md) and the [Known limitations](https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md), or [open an issue](https://github.com/gultyayev/ngx-virtual-dnd/issues) with a minimal reproduction.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/more/limitations.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Known limitations

## Scope

- **Vertical lists only.** Lists scroll and reorder vertically. Horizontal lists, grids with 2D reordering and freeform canvases are not supported. A board of side-by-side vertical columns works.
- **Items move between lists, never outside them.** There is no free dragging to an arbitrary position, and no dropping files from the desktop.
- **No enter predicate.** A droppable has no input that rejects some items. Bind its `disabled` input from the drag state instead; see [Accepting only some items](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/multiple-lists.md#accepting-only-some-items).

## Hit-testing

Because hit-testing uses geometry rather than `elementFromPoint()`, some browser behavior is not reproduced:

- **Overlays do not block drops.** A modal or toolbar painted over a droppable does not stop the droppable underneath from being hit.
- **Stacking order is approximated.** "Last in document order wins" matches the paint order in most layouts. It does not follow `z-index` or stacking contexts, so a droppable earlier in the DOM but raised visually loses to a later sibling.

If your layout depends on either, keep overlapping droppables in different groups, or avoid painting interactive overlays across active drop targets during a drag.

## Drag preview

- **The default preview duplicates IDs.** The clone keeps the `id` attributes of the item and everything in it, so styles that select the item through an ID keep applying to the preview. During a drag the item is hidden (`display: none`), not removed, so the document has two elements with each of those IDs. `getElementById()` and `querySelector('#…')` find whichever comes first in the document, usually the item. A `<label for>`, an `aria-labelledby`, or an SVG reference such as `url(#gradient)` or `<use href="#icon">` in the preview can resolve to the hidden item, and browsers may not paint an SVG gradient or symbol that is inside a hidden element. The preview is `inert` and `aria-hidden="true"`, so nothing in it takes focus or reaches screen readers. If duplicate IDs matter in your app, use a [custom preview template](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md#custom-preview).

## Shadow DOM

Lists, items and the drag preview work inside an open shadow root, for example in a component with `ViewEncapsulation.ShadowDom`. Droppables register themselves rather than being found by a document query, and the lookups that walk up from an element (the list of an item, the `vdndScrollable` container of a list) continue from a shadow root to its host. Some things still need care:

- **An item must be in the same DOM tree as its list.** A list finds its items with `querySelectorAll()`, which does not look into shadow roots. For a row component that uses shadow DOM, put `vdndDraggable` on the component's host element, not on an element inside its shadow root. Items slotted (`<slot>`) into a list that a web component renders in its shadow root are not found either.
- **Only open shadow roots are supported.** Nothing can look into a closed one from outside: `PositionCalculatorService.findDraggableAtPoint()`, for example, stops at its host.
- **The preview leaves the shadow root.** It moves to a container under `<body>`, where the shadow root's styles (its `<style>` elements and `adoptedStyleSheets`) don't apply. The default preview still looks like the item, because the clone gets the item's computed styles inline. A custom preview template declared in a shadow-DOM component loses that component's styles, so style it from a global stylesheet. An item that is itself a shadow host previews without its shadow content (cloning an element does not copy its shadow root); give it a custom preview template.
- **No grabbing cursor inside shadow roots.** The `cursor: grabbing` the library sets during a drag comes from a document stylesheet, which does not reach into shadow roots. Lists and items there keep their own cursor.

## Animations on rows that move

This is a limitation of Angular. The lists move a row's view with `ViewContainerRef.move()`, as `*ngFor` does, and Angular animates a view that moves as if it left and came back: it plays the row's leave animation (`animate.leave`) and its enter animation (`animate.enter`). Only `@for` avoids that. Rows move when the items change order, for example after a drop or a sort. A row in `stickyItemIds` also moves each time it scrolls past the edge of the rendered rows.

What happens to a row with `animate.leave` then depends on the Angular version:

- Before Angular 21.2.1, Angular removes the row from the page when its leave animation ends, so it disappears.
- From Angular 21.2.1, the row stays, unless it moves again before its leave animation ends: then Angular removes it.
- On Angular 21, the row also keeps its leave class after the animation. A leave style that holds its end state, such as a transition to `opacity: 0`, leaves the row invisible.

To avoid it during a drag, turn the animations off: give `[animate.leave]` an empty value from `dragStart` until the drop has rendered. Angular reads the value when the animation runs, after the render that moves the rows, so turn it back on in the `read` phase of that render:

```ts
readonly leaveAnimation = signal('row-leave');
readonly #injector = inject(Injector);

onDragStart(): void {
  this.leaveAnimation.set('');
}

onDragEnd(): void {
  // Angular runs the leave animations of the moved rows before the read phase of the next render
  afterNextRender(
    { read: () => this.leaveAnimation.set('row-leave') },
    { injector: this.#injector },
  );
}
```

```html
<div
  class="item"
  [animate.leave]="leaveAnimation()"
  [vdndDraggable]="item.id"
  (dragStart)="onDragStart()"
  (dragEnd)="onDragEnd()"
></div>
```

Bind `[animate.enter]` to a signal and clear it the same way, so moved rows don't replay their enter animation either.

Before Angular 21.2.1 this is not enough, because Angular removes a row that moves even when its leave animation is empty. Update Angular, or keep `animate.leave` off rows that can move.

This only covers drags. Turn the animations off the same way around a sort of your own, and keep `animate.leave` off rows in `stickyItemIds`: they move while the list scrolls. A bound `[animate.leave]` also keeps a row from being recycled, even while its value is empty (see [Row recycling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md#row-recycling)).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/more/how-it-works.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

***

title: How it works
description: Geometric hit-testing, placeholder math and rendering: what happens inside a drag.
-----------------------------------------------------------------------------------------------

# How it works

## The problem

Typical drag-and-drop libraries find the drop position by calling `getBoundingClientRect()` on sibling elements. A virtual list renders only the rows in view, so most siblings do not exist and that approach breaks.

## Geometric hit-testing

When a drag starts, ngx-virtual-dnd records the drop targets in the active group and their bounding rectangles. On each pointer move it compares the pointer position with those cached rectangles, instead of asking the browser which element is under the pointer. This avoids forcing a layout recalculation on every frame of the drag.

The cache updates itself:

- rectangles are re-read after scroll and resize, and when a target resizes (through `ResizeObserver`)
- targets mounted or removed during the drag are added or dropped
- each rectangle is clipped to its nearest `vdndScrollable` ancestor, so a list scrolled out of view inside a container cannot be hit

When rectangles overlap, the last one in document order wins.

## Placeholder math

Once the target list is known, the drop index comes from arithmetic, not DOM queries:

- The probe point is the dragged preview's center, capped at half an item below the preview's top edge, so tall items do not jump ahead of the pointer.
- **Fixed heights:** the index is `floor((probeY - listTop + scrollTop) / itemHeight)`.
- **Dynamic heights:** a binary search over prefix sums of measured heights finds the row under the probe. The placeholder only moves past that row once the preview's top edge crosses the row's midpoint, so a short item entering a tall row needs half of that row's height.

While an item is dragged within its own list it is hidden with `display: none` and the placeholder takes its slot. The list's total height stays the same, so content below the list does not shift. The index calculation accounts for the hidden item, so the logical position stays correct.

## Rendering

Pointer moves are coalesced into a single `requestAnimationFrame` loop that reads layout, computes the new state and then writes styles, in that order. Drag state lives in signals, so only the parts of the page that depend on it update. The loop and all high-frequency listeners run outside Angular's zone. The `dragStart`, `dragEnd` and `drop` outputs are emitted inside it, so handlers that change plain fields still render in zone.js apps.

## Row recycling

`<vdnd-sortable-list>` and `<vdnd-virtual-scroll>` can reuse the view of a row that scrolls out to render a row that scrolls in, and `*vdndVirtualFor` always does. See [Row recycling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md#row-recycling) for what that means for your row components.

## Browser support

The latest versions of Chrome, Edge, Firefox and Safari, on desktop and mobile. Every change runs the end-to-end suite in Chromium, Firefox and WebKit, with mobile touch runs in Chromium and WebKit.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/guide/more/ai-assistants.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# AI assistants

Coding assistants often guess at a library's API. ngx-virtual-dnd provides two sources they can read instead.

## Agent skill

The **ngx-virtual-dnd** skill teaches an assistant how to integrate the library. It covers setup, the [rules that fail silently](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/core-concepts.md#rules-that-fail-silently), recipes and the full API reference. Install it into your project:

```bash
npx skills add gultyayev/ngx-virtual-dnd
```

It works with Claude Code, Cursor, Windsurf, GitHub Copilot and [more than 40 other agents](https://skills.sh). The assistant loads the skill when a task involves the library, for example "make this list sortable" or "let tasks move between these columns".

The skill's source is in the repository under [`skills/ngx-virtual-dnd`](https://github.com/gultyayev/ngx-virtual-dnd/tree/master/skills/ngx-virtual-dnd).

## llms.txt

This site is also published as Markdown for language models:

| URL                                                                           | Contents                                 |
| ----------------------------------------------------------------------------- | ---------------------------------------- |
| [`/llms.txt`](https://gultyayev.github.io/ngx-virtual-dnd/llms.txt)           | Index of every page with a short summary |
| [`/llms-full.txt`](https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt) | The whole site in one file               |
| `<page>.md`                                                                   | Any single page as Markdown              |

Paste one of these URLs into a chat, or point a tool at it. On every page, the outline sidebar also has buttons to copy the page as Markdown or open it in Claude or ChatGPT.

## Example prompt

> Using ngx-virtual-dnd, turn the task list in `tasks.component.ts` into a sortable list that can hold 5,000 items. Keep the existing task template and persist the new order with `TasksService.reorder()`.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/overview.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# API overview

Everything is exported from `ngx-virtual-dnd`. Most apps only use the exports in the first two tables.

## Start here

| Export                                                                                                                                                | Use it to                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`VirtualSortableListComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#virtualsortablelistcomponent) (`<vdnd-sortable-list>`) | Render a sortable virtual list: droppable, scroller and placeholder in one |
| [`DraggableDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#draggabledirective) (`[vdndDraggable]`)                          | Make an item draggable                                                     |
| [`DroppableGroupDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#droppablegroupdirective) (`[vdndGroup]`)                    | Name the group that lets lists exchange items                              |
| [`DragPreviewComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#dragpreviewcomponent) (`<vdnd-drag-preview>`)                  | Render the element that follows the pointer (place it once)                |
| [`DropEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#dropevent)                                                                    | Read where an item came from and where it was dropped                      |
| [`moveItem`, `reorderItems`, `applyMove`](https://gultyayev.github.io/ngx-virtual-dnd/api/utilities.md)                                               | Apply a drop to your signals or immutable state                            |

## Events and helpers

| Export                                                                                                   | Use it to                                                               |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [`DragStartEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#dragstartevent)             | React to a drag starting (`(dragStart)` on a draggable)                 |
| [`DragEndEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#dragendevent)                 | React to every drag ending, dropped or not (`(dragEnd)` on a draggable) |
| [`PlaceholderMoveEvent`](https://gultyayev.github.io/ngx-virtual-dnd/api/events.md#placeholdermoveevent) | Give feedback on every placeholder step (haptics, announcements)        |
| [`isNoOpDrop`, `insertAt`, `removeAt`](https://gultyayev.github.io/ngx-virtual-dnd/api/utilities.md)     | Skip drops back to the same place, or edit arrays immutably             |
| [`DragStateService`](https://gultyayev.github.io/ngx-virtual-dnd/api/services.md#dragstateservice)       | Read the current drag anywhere in the app, as signals                   |
| [`VDND_ANIMATION_CONFIG`](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#injection-tokens)     | Turn on shift and drop animations                                       |
| [`AutoScrollConfig`](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#configuration)             | Type of the `autoScrollConfig` input                                    |

## Other list building blocks

Use these instead of `<vdnd-sortable-list>` when you need your own markup or page-level scrolling. See [Choosing a component](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/choosing-a-component.md).

| Export                                                                                                                                                       | Use it to                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| [`DroppableDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#droppabledirective) (`[vdndDroppable]`)                                 | Make your own element a drop target                               |
| [`VirtualScrollContainerComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#virtualscrollcontainercomponent) (`<vdnd-virtual-scroll>`) | Virtual scroller inside a `vdndDroppable`, with scrolling methods |
| [`ScrollableDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#scrollabledirective) (`[vdndScrollable]`)                              | Mark the element that scrolls, for page-level scrolling           |
| [`VirtualContentComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#virtualcontentcomponent) (`<vdnd-virtual-content>`)                | Virtual rows inside a `vdndScrollable`                            |
| [`ContentHeaderDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#contentheaderdirective) (`[vdndContentHeader]`)                     | Measure a header above the rows of `<vdnd-virtual-content>`       |
| [`VirtualForDirective`](https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md#virtualfordirective) (`*vdndVirtualFor`)                               | Render only the visible items, as a structural directive          |
| [`VirtualViewportComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#virtualviewportcomponent) (`<vdnd-virtual-viewport>`)             | Self-scrolling container for `*vdndVirtualFor`                    |

## Advanced

Most apps never need these. They exist for custom containers and low-level integrations.

| Export                                                                                                                                                                                      | What it is                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`AutoScrollService`](https://gultyayev.github.io/ngx-virtual-dnd/api/services.md#autoscrollservice)                                                                                        | Edge scrolling during drags                                            |
| [`PositionCalculatorService`, `ElementCloneService`, `KeyboardDragService`, `OverlayContainerService`](https://gultyayev.github.io/ngx-virtual-dnd/api/services.md#advanced-services)       | Internals exported for customization                                   |
| [`PlaceholderComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#placeholdercomponent) (`<vdnd-placeholder>`)                                                         | A drop indicator you render yourself; the built-in lists do not use it |
| [`DragPlaceholderComponent`](https://gultyayev.github.io/ngx-virtual-dnd/api/components.md#dragplaceholdercomponent) (`<vdnd-drag-placeholder>`)                                            | The placeholder the built-in lists render                              |
| [`VirtualScrollStrategy`, `FixedHeightStrategy`, `DynamicHeightStrategy`](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#strategies)                                              | Virtual scroll math, for building your own container                   |
| [`VDND_SCROLL_CONTAINER`, `VDND_VIRTUAL_VIEWPORT`, `VDND_GROUP_TOKEN`](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#injection-tokens)                                           | Tokens the library's containers provide                                |
| [Template contexts](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#template-contexts) and [drag state types](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#drag-state) | Types of template variables and of `DragStateService` values           |
| [`END_OF_LIST`, `INITIAL_DRAG_STATE`](https://gultyayev.github.io/ngx-virtual-dnd/api/types.md#constants)                                                                                   | Constants. `END_OF_LIST` is deprecated                                 |



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/components.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Components

All components are standalone and exported from `ngx-virtual-dnd`.

## VirtualSortableListComponent

**Selector:** `vdnd-sortable-list`

Droppable, virtual scroller and placeholder in one element. The default choice. See the [Quick start](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md).

| Input                  | Type                                           | Default                 | Description                                                                                                                                                                                            |
| ---------------------- | ---------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `droppableId`          | `string`                                       | **required**            | Unique ID of this list                                                                                                                                                                                 |
| `items`                | `T[]`                                          | **required**            | Items to render                                                                                                                                                                                        |
| `itemHeight`           | `number`                                       | **required**            | Row height in px (the estimate when `dynamicItemHeight` is on)                                                                                                                                         |
| `itemIdFn`             | `(item: T) => string`                          | **required**            | Returns an item's ID; must equal the `vdndDraggable` value rendered for it                                                                                                                             |
| `itemTemplate`         | `TemplateRef<VirtualScrollItemContext<T>>`     | **required**            | Row template; its root element carries `vdndDraggable`                                                                                                                                                 |
| `group`                | `string`                                       | —                       | Group name. Not needed inside a `vdndGroup`                                                                                                                                                            |
| `containerHeight`      | `number`                                       | —                       | Height in px. Without it, give the inner `vdnd-virtual-scroll` a CSS height                                                                                                                            |
| `dynamicItemHeight`    | `boolean`                                      | `false`                 | Measure rows instead of using a fixed height                                                                                                                                                           |
| `trackByFn`            | `(index: number, item: T) => string \| number` | derived from `itemIdFn` | Track-by function for rendering                                                                                                                                                                        |
| `droppableData`        | `unknown`                                      | —                       | Arbitrary data, delivered as `DropEvent.destination.data`                                                                                                                                              |
| `disabled`             | `boolean`                                      | `false`                 | Stop items being dropped into this list (items can still be dragged out; set `disabled` on the draggables too for a read-only list)                                                                    |
| `overscan`             | `number`                                       | `3`                     | Rows rendered beyond the visible area, above and below                                                                                                                                                 |
| `recycleRows`          | `boolean`                                      | `false`                 | Reuse the views of rows that scroll out, see [Row recycling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md#row-recycling). Added in 3.3.0                                  |
| `autoScrollEnabled`    | `boolean`                                      | `true`                  | Scroll when dragging near the edges                                                                                                                                                                    |
| `autoScrollConfig`     | `Partial<AutoScrollConfig>`                    | `{}`                    | Auto-scroll tuning, see [Auto-scroll](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/auto-scroll.md)                                                                                       |
| `constrainToContainer` | `boolean`                                      | `false`                 | Keep the preview and drop position inside the list                                                                                                                                                     |
| `scrollInsetTop`       | `number`                                       | `0`                     | Height (px) of content overlaid on the top of the rows; they start below it. See [Scroll insets](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md#sticky-headers-and-footers) |
| `scrollInsetBottom`    | `number`                                       | `0`                     | Height (px) of content overlaid on the bottom of the rows; the last one scrolls clear of it                                                                                                            |

| Output            | Type                   | Description                                                                     |
| ----------------- | ---------------------- | ------------------------------------------------------------------------------- |
| `drop`            | `DropEvent`            | An item was dropped into this list                                              |
| `placeholderMove` | `PlaceholderMoveEvent` | The placeholder moved within this list (every row displacement). Added in 3.2.0 |

The item template context (`VirtualScrollItemContext<T>`) exposes `$implicit` (the item), `index` (position in the full list) and `isSticky`.

## VirtualScrollContainerComponent

**Selector:** `vdnd-virtual-scroll`

Low-level virtual scroller. Place it inside an element with `vdndDroppable`. See [Choosing a component](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/choosing-a-component.md#low-level-scroller).

| Input                   | Type                                           | Default                 | Description                                                                                 |
| ----------------------- | ---------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| `items`                 | `T[]`                                          | **required**            | Items to render                                                                             |
| `itemHeight`            | `number`                                       | **required**            | Row height in px                                                                            |
| `itemIdFn`              | `(item: T) => string`                          | **required**            | Returns an item's ID; must equal its `vdndDraggable` value                                  |
| `itemTemplate`          | `TemplateRef<VirtualScrollItemContext<T>>`     | **required**            | Row template                                                                                |
| `droppableId`           | `string`                                       | —                       | ID of the enclosing `vdndDroppable`; needed to show the placeholder                         |
| `containerHeight`       | `number`                                       | —                       | Height in px. Without it, give the element a CSS height                                     |
| `dynamicItemHeight`     | `boolean`                                      | `false`                 | Measure rows                                                                                |
| `trackByFn`             | `(index: number, item: T) => string \| number` | derived from `itemIdFn` | Track-by function                                                                           |
| `overscan`              | `number`                                       | `3`                     | Extra rows rendered above and below                                                         |
| `recycleRows`           | `boolean`                                      | `false`                 | Reuse the views of rows that scroll out. Added in 3.3.0                                     |
| `stickyItemIds`         | `string[]`                                     | `[]`                    | IDs of items that stay rendered at any scroll position                                      |
| `autoStickyDraggedItem` | `boolean`                                      | `true`                  | Keep the dragged item rendered while it is out of view                                      |
| `scrollContainerId`     | `string`                                       | —                       | ID used to register the container for auto-scroll                                           |
| `autoScrollEnabled`     | `boolean`                                      | `true`                  | Scroll when dragging near the edges                                                         |
| `autoScrollConfig`      | `Partial<AutoScrollConfig>`                    | `{}`                    | Auto-scroll tuning                                                                          |
| `scrollInsetTop`        | `number`                                       | `0`                     | Height (px) of content overlaid on the top of the rows; they start below it                 |
| `scrollInsetBottom`     | `number`                                       | `0`                     | Height (px) of content overlaid on the bottom of the rows; the last one scrolls clear of it |

| Method            | Signature                    | Description                  |
| ----------------- | ---------------------------- | ---------------------------- |
| `scrollTo`        | `(position: number) => void` | Scroll to an absolute offset |
| `scrollToIndex`   | `(index: number) => void`    | Scroll to an item by index   |
| `scrollBy`        | `(delta: number) => void`    | Scroll by a relative amount  |
| `getScrollTop`    | `() => number`               | Current scroll offset        |
| `getScrollHeight` | `() => number`               | Total scroll height          |

Get the instance with `viewChild(VirtualScrollContainerComponent)`.

## VirtualViewportComponent

**Selector:** `vdnd-virtual-viewport`

Self-scrolling container for `*vdndVirtualFor`. Positions all rows with one GPU-accelerated transform. Children inherit `itemHeight` and `dynamicItemHeight`. Needs a CSS height.

| Input               | Type                        | Default      | Description                                                                                                         |
| ------------------- | --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `itemHeight`        | `number`                    | **required** | Row height in px                                                                                                    |
| `dynamicItemHeight` | `boolean`                   | `false`      | Measure rows                                                                                                        |
| `contentOffset`     | `number`                    | `0`          | Space in px reserved above the rows                                                                                 |
| `scrollContainerId` | `string`                    | —            | ID used to register for auto-scroll                                                                                 |
| `autoScrollEnabled` | `boolean`                   | `true`       | Scroll when dragging near the edges                                                                                 |
| `autoScrollConfig`  | `Partial<AutoScrollConfig>` | `{}`         | Auto-scroll tuning                                                                                                  |
| `scrollInsetTop`    | `number`                    | `0`          | Height (px) of content pinned over the top edge; the rows start below it, or `contentOffset` down when that is more |
| `scrollInsetBottom` | `number`                    | `0`          | Height (px) of content pinned over the bottom edge; the last row scrolls clear of it                                |

## VirtualContentComponent

**Selector:** `vdnd-virtual-content`

Virtual rows inside an external scroll container, for [page-level scrolling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md). Must be inside a `vdndScrollable` element. Projects an optional `[vdndContentHeader]` above the rows.

| Input               | Type      | Default      | Description                                                                |
| ------------------- | --------- | ------------ | -------------------------------------------------------------------------- |
| `itemHeight`        | `number`  | **required** | Row height in px                                                           |
| `dynamicItemHeight` | `boolean` | `false`      | Measure rows                                                               |
| `contentOffset`     | `number`  | `0`          | Offset above the rows; replaced by the measured `vdndContentHeader` height |

## DragPreviewComponent

**Selector:** `vdnd-drag-preview`

Renders the element that follows the pointer. **Required**: place it once. It moves itself into a body-level `div.vdnd-overlay-container`. The preview box is `inert` and `aria-hidden="true"`. See [Preview and placeholder](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/preview-and-placeholder.md).

| Input             | Type                                 | Default          | Description                                               |
| ----------------- | ------------------------------------ | ---------------- | --------------------------------------------------------- |
| `previewTemplate` | `TemplateRef<DragPreviewContext<T>>` | —                | Custom preview; replaces the default clone                |
| `cursorOffset`    | `{ x: number; y: number }`           | `{ x: 8, y: 8 }` | Fallback offset, used only when the grab point is unknown |

## PlaceholderComponent

**Selector:** `vdnd-placeholder`

A drop-position indicator you render yourself. The built-in lists do not use it; they render `DragPlaceholderComponent`.

| Input      | Type                              | Default | Description                |
| ---------- | --------------------------------- | ------- | -------------------------- |
| `height`   | `number`                          | `50`    | Height in px               |
| `template` | `TemplateRef<PlaceholderContext>` | —       | Custom placeholder content |

## DragPlaceholderComponent

**Selector:** `vdnd-drag-placeholder`

The empty placeholder that the lists render at the drop position, sized to the dragged item. You rarely use it directly; style it through `.vdnd-drag-placeholder`.

| Input        | Type     | Default      | Description  |
| ------------ | -------- | ------------ | ------------ |
| `itemHeight` | `number` | **required** | Height in px |



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/directives.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Directives

## DraggableDirective

**Selector:** `[vdndDraggable]`

Makes an element draggable with mouse, touch and keyboard. See [Drag behavior](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/drag-behavior.md).

| Input                | Type                 | Default      | Description                                                                                |
| -------------------- | -------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `vdndDraggable`      | `string`             | **required** | Unique ID across all lists; must equal the list's item ID                                  |
| `vdndDraggableGroup` | `string`             | —            | Group name. Required unless a `vdndGroup` is in scope where the template is declared       |
| `vdndDraggableData`  | `unknown`            | —            | Arbitrary data, delivered in drag events, `DropEvent.source.data` and the preview template |
| `disabled`           | `boolean`            | `false`      | Prevent dragging                                                                           |
| `dragHandle`         | `string`             | —            | CSS selector; only presses inside a match within the item start a drag                     |
| `dragThreshold`      | `number`             | `5`          | Distance in px before a drag starts                                                        |
| `dragDelay`          | `number`             | `0`          | Hold time in ms before a drag can start                                                    |
| `lockAxis`           | `'x' \| 'y' \| null` | `null`       | Axis to freeze: `'x'` moves vertically only, `'y'` horizontally only                       |

| Output      | Type             | Description                                           |
| ----------- | ---------------- | ----------------------------------------------------- |
| `dragStart` | `DragStartEvent` | A drag started                                        |
| `dragEnd`   | `DragEndEvent`   | A drag ended, dropped or not (see `destinationIndex`) |

## DroppableDirective

**Selector:** `[vdndDroppable]`

Marks an element as a drop target.

| Input                  | Type                        | Default      | Description                                                                                      |
| ---------------------- | --------------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `vdndDroppable`        | `string`                    | **required** | Unique ID on the page                                                                            |
| `vdndDroppableGroup`   | `string`                    | —            | Group name. Required unless inherited from a `vdndGroup` ancestor                                |
| `vdndDroppableData`    | `unknown`                   | —            | Arbitrary data, delivered as `DropEvent.destination.data`                                        |
| `disabled`             | `boolean`                   | `false`      | Skip this target for pointer and keyboard; releasing over it emits no `drop`                     |
| `autoScrollEnabled`    | `boolean`                   | `true`       | Scroll when dragging near the edges                                                              |
| `autoScrollConfig`     | `Partial<AutoScrollConfig>` | `{}`         | Auto-scroll tuning                                                                               |
| `constrainToContainer` | `boolean`                   | `false`      | Keep the preview and drop position inside the nearest `vdndScrollable` ancestor, or this element |

| Output            | Type                   | Description                                                                          |
| ----------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `drop`            | `DropEvent`            | An item was dropped here (destination only; at release, right after `dragEnd`)       |
| `placeholderMove` | `PlaceholderMoveEvent` | The placeholder moved within this droppable (every row displacement). Added in 3.2.0 |

## DroppableGroupDirective

**Selector:** `[vdndGroup]`

Provides a group name to every draggable and droppable inside it. Declare item templates inside this element as well.

| Input       | Type     | Default      | Description |
| ----------- | -------- | ------------ | ----------- |
| `vdndGroup` | `string` | **required** | Group name  |

## ScrollableDirective

**Selector:** `[vdndScrollable]`

Marks the element that scrolls for `<vdnd-virtual-content>` or `*vdndVirtualFor`. The element needs `overflow: auto` (or `scroll`) and a height. Adds the `vdnd-scrollable` class and `overflow-anchor: none`, and `data-scroll-inset-top` / `data-scroll-inset-bottom` while `scrollInsetTop` / `scrollInsetBottom` are not 0. A `*vdndVirtualFor` used directly inside it sets `position: relative` on it when it is not positioned (see [VirtualForDirective](#virtualfordirective)).

| Input               | Type                        | Default | Description                                                              |
| ------------------- | --------------------------- | ------- | ------------------------------------------------------------------------ |
| `scrollContainerId` | `string`                    | —       | ID used to register for auto-scroll                                      |
| `autoScrollEnabled` | `boolean`                   | `true`  | Scroll when dragging near the edges                                      |
| `autoScrollConfig`  | `Partial<AutoScrollConfig>` | `{}`    | Auto-scroll tuning                                                       |
| `scrollInsetTop`    | `number`                    | `0`     | Height (px) of content pinned over the top edge, e.g. a sticky header    |
| `scrollInsetBottom` | `number`                    | `0`     | Height (px) of content pinned over the bottom edge, e.g. a sticky footer |

`scrollInsetTop` and `scrollInsetBottom` tell a drag which part of the element sticky content inside it covers. You measure the heights; the drag treats the element as the part between them: `constrainToContainer` keeps the preview there, the auto-scroll zones start at its edges (a pointer over the sticky content scrolls at full speed), a pointer over the sticky content is not over the lists in the element (nor in scroll containers nested in it), and a keyboard drag keeps the placeholder clear of it. See [Sticky headers and footers](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/page-scroll.md#sticky-headers-and-footers).

## VirtualForDirective

**Selector:** `*vdndVirtualFor`

Structural directive that renders only the visible items. Use it inside `<vdnd-virtual-viewport>`, `<vdnd-virtual-content>` or a `vdndScrollable` element.

```angular-html
<ng-container
  *vdndVirtualFor="let task of tasks(); trackBy: trackById; itemHeight: 48; overscan: 3"
>
  <div [vdndDraggable]="task.id">{{ task.title }}</div>
</ng-container>
```

| Key                 | Type                                  | Default      | Description                                           |
| ------------------- | ------------------------------------- | ------------ | ----------------------------------------------------- |
| `of`                | `T[]`                                 | **required** | Items                                                 |
| `trackBy`           | `(index: number, item: T) => unknown` | **required** | Must return the same ID as the item's `vdndDraggable` |
| `itemHeight`        | `number`                              | inherited    | Required when not inside a viewport component         |
| `dynamicItemHeight` | `boolean`                             | inherited    | Measure rows                                          |
| `droppableId`       | `string`                              | inherited    | Taken from the enclosing `vdndDroppable`              |
| `overscan`          | `number`                              | `3`          | Extra rows rendered above and below                   |

Template context (`VirtualForContext<T>`): `$implicit`, `index`, `first`, `last`, `count`.

It always recycles rows: the view of a row that scrolls out renders a row that scrolls in. See [Row recycling](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/performance.md#row-recycling).

Used directly in a `vdndScrollable` element (no viewport component), it positions each row absolutely at its offset and opens a gap for the drag placeholder by moving the rows after it down. The rows scroll with the element only if it is their containing block, so when neither the element nor an element between it and the rows is positioned, the directive sets `position: relative` on it.

```angular-html
<div vdndScrollable vdndDroppable="tasks" (drop)="onDrop($event)" style="overflow: auto; height: 400px">
  <ng-container *vdndVirtualFor="let task of tasks(); itemHeight: 48; trackBy: trackById">
    <div [vdndDraggable]="task.id">{{ task.title }}</div>
  </ng-container>
</div>
```

## ContentHeaderDirective

**Selector:** `[vdndContentHeader]`

Marks a header projected into `<vdnd-virtual-content>`. Its height is measured and used as the content offset. No inputs or outputs.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/events.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Events

| Output              | Event                  | Emitted by                                                                        |
| ------------------- | ---------------------- | --------------------------------------------------------------------------------- |
| `(dragStart)`       | `DragStartEvent`       | `vdndDraggable`                                                                   |
| `(dragEnd)`         | `DragEndEvent`         | `vdndDraggable`, after every drag, dropped or not                                 |
| `(drop)`            | `DropEvent`            | `vdndDroppable` and `<vdnd-sortable-list>`, on the destination only               |
| `(placeholderMove)` | `PlaceholderMoveEvent` | `vdndDroppable` and `<vdnd-sortable-list>`, each time the placeholder moves in it |

On release, `(dragEnd)` fires first, then `(drop)` on the destination, both before the next render.

## DragStartEvent

```ts
interface DragStartEvent {
  draggableId: string;
  droppableId: string; // the list the drag started in
  data?: unknown; // vdndDraggableData
  position: CursorPosition;
  sourceIndex: number;
}
```

## DropEvent

```ts
interface DropEvent {
  source: DropSource;
  destination: DropDestination;
}

interface DropSource {
  draggableId: string;
  droppableId: string;
  index: number;
  data?: unknown; // vdndDraggableData
}

interface DropDestination {
  droppableId: string;
  placeholderId: string; // deprecated: always END_OF_LIST; use index for the position
  index: number; // final insertion index, after removal from the source
  data?: unknown; // vdndDroppableData / droppableData
}
```

Apply the move with [`moveItem()`, `reorderItems()` or `applyMove()`](https://gultyayev.github.io/ngx-virtual-dnd/api/utilities.md).

## DragEndEvent

```ts
interface DragEndEvent {
  draggableId: string;
  droppableId: string; // the source list
  cancelled: boolean;
  data?: unknown;
  sourceIndex: number;
  destinationIndex: number | null;
}
```

`destinationIndex` is `null` when nothing was dropped. That happens when:

- the drag was **cancelled**, by any of:
  - <kbd>
      Escape
    </kbd>
  - <kbd>Tab</kbd> during a keyboard drag
  - the window losing focus during a pointer drag
  - the page being hidden during a pointer drag (the release would never reach the page)
  - the system cancelling a touch
  - the dragged draggable being destroyed (for example its item removed from the list mid-drag)
- the item was released outside every droppable
- the item was released over a disabled droppable

A non-null value means a `drop` event fired on the destination. `cancelled` is `true` only in the first case, so check `destinationIndex === null` to detect "no drop".

## PlaceholderMoveEvent

Added in 3.2.0.

```ts
interface PlaceholderMoveEvent {
  draggableId: string;
  sourceDroppableId: string; // the list the drag started in
  droppableId: string; // the list the placeholder moved within
  previousIndex: number | null; // null when the placeholder just entered this list
  currentIndex: number;
  data?: unknown; // vdndDraggableData
}
```

Emitted each time the placeholder moves within a list, including when it enters the list. It is not emitted for the initial pick-up or when the placeholder leaves. Indexes follow the `DropEvent.destination.index` convention: where the item would land if dropped now. For the first move in the source list, `previousIndex` is the item's original index.

Each event reports one placeholder update. During a fast pointer drag the placeholder can skip rows between updates, so `currentIndex` may differ from `previousIndex` by more than one.

Listening runs change detection: like any Angular template listener, `(placeholderMove)` marks your component and its ancestors for check each time it fires. A list without the listener does not re-render your component on placeholder moves.

Typical uses are [haptic feedback](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md#placeholder-move-events) and [screen reader announcements](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/accessibility.md#screen-reader-announcements).



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/utilities.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Utilities

See [Handling drops](https://gultyayev.github.io/ngx-virtual-dnd/guide/essentials/handling-drops.md) for how to choose between them.

## moveItem

```ts
function moveItem<T>(event: DropEvent, lists: Record<string, WritableSignal<T[]>>): void;
```

Moves the item between (or within) signal-based lists, keyed by droppable ID. Same-list drops are delegated to `reorderItems`. If either droppable ID is missing from `lists`, or the source item does not exist, nothing happens and a warning is logged in dev mode.

## reorderItems

```ts
function reorderItems<T>(event: DropEvent, list: WritableSignal<T[]>): void;
```

Reorders a single signal-based list. Use it for same-list drops only. If the source item does not exist (for example, the list changed during the drag), nothing happens and a warning is logged in dev mode.

## applyMove

```ts
function applyMove<T>(event: DropEvent, lists: Record<string, T[]>): Record<string, T[]>;
```

Immutable version for stores. Returns a shallow copy of `lists` with new arrays for the source and destination. If the source item does not exist, it returns a shallow copy with the original arrays.

## isNoOpDrop

```ts
function isNoOpDrop(event: DropEvent): boolean;
```

`true` when the source and destination droppable and index are equal, meaning the item was dropped where it started.

## insertAt / removeAt

```ts
function insertAt<T>(list: T[], item: T, index: number): T[];
function removeAt<T>(list: T[], index: number): T[];
```

Return new arrays; the input is not modified.



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/services.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Services

All services are root singletons (`providedIn: 'root'`).

## DragStateService

Read-only signals describing the current drag. Inject it to react to drags anywhere in the app:

```ts
protected readonly dragState = inject(DragStateService);
```

```angular-html
@if (dragState.isDragging()) {
  <p class="hint">Drop the item into a list</p>
}
```

| Signal                | Type                     | Description                                                                                      |
| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `isDragging`          | `boolean`                | A drag is in progress                                                                            |
| `draggedItem`         | `DraggedItem \| null`    | The dragged item, its element and size                                                           |
| `draggedItemId`       | `string \| null`         | ID of the dragged item                                                                           |
| `sourceDroppableId`   | `string \| null`         | List the drag started in                                                                         |
| `sourceIndex`         | `number \| null`         | Index the drag started at                                                                        |
| `activeDroppableId`   | `string \| null`         | List currently targeted                                                                          |
| `placeholderId`       | `string \| null`         | **Deprecated**, use `placeholderIndex`. `END_OF_LIST` while a list is targeted, otherwise `null` |
| `placeholderIndex`    | `number \| null`         | Current drop index                                                                               |
| `cursorPosition`      | `CursorPosition \| null` | Pointer position                                                                                 |
| `grabOffset`          | `GrabOffset \| null`     | Offset between the pointer and the item's top-left corner                                        |
| `initialPosition`     | `CursorPosition \| null` | Pointer position at drag start                                                                   |
| `lockAxis`            | `'x' \| 'y' \| null`     | Axis lock of the current drag                                                                    |
| `isKeyboardDrag`      | `boolean`                | The drag was started with the keyboard                                                           |
| `keyboardTargetIndex` | `number \| null`         | Target index during a keyboard drag                                                              |
| `wasCancelled`        | `boolean`                | Whether the last drag was cancelled                                                              |
| `endedDragState`      | `DragState \| null`      | Snapshot of the last drag, taken just before it was reset                                        |

For styling a single list, the `vdnd-droppable-active` class is usually simpler.

## AutoScrollService

Edge scrolling during drags. It is normally configured through component inputs.

| Method                | Signature                        | Description                   |
| --------------------- | -------------------------------- | ----------------------------- |
| `registerContainer`   | `(id, element, config?) => void` | Register a scroll container   |
| `unregisterContainer` | `(id) => void`                   | Unregister a scroll container |
| `startMonitoring`     | `(onScroll?) => void`            | Start watching the pointer    |
| `stopMonitoring`      | `() => void`                     | Stop watching                 |
| `isScrolling`         | `() => boolean`                  | Whether auto-scroll is active |
| `getScrollDirection`  | `() => { x: number; y: number }` | Current scroll direction      |

## Advanced services

These are exported for advanced customization. Most apps never need them.

| Service                     | Purpose                                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PositionCalculatorService` | Hit-testing and drop-index math over the lists rendered with `vdndDroppable`. `refreshCandidates()` re-reads the drop targets of an active drag. |
| `ElementCloneService`       | Clones an element with its computed styles inlined, minus the root's placement and its focusability; used for the default preview.               |
| `KeyboardDragService`       | Keyboard drag state.                                                                                                                             |
| `OverlayContainerService`   | The body-level container that hosts the drag preview.                                                                                            |



---
url: https://gultyayev.github.io/ngx-virtual-dnd/api/types.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Types, tokens and strategies

## Configuration

```ts
interface AutoScrollConfig {
  threshold: number; // distance from the edge that starts scrolling (px). Default 50
  maxSpeed: number; // max speed in px per 60 fps frame. Default 15
  accelerate: boolean; // faster closer to the edge. Default true
}

interface VdndAnimationConfig {
  shiftDuration?: number; // slide duration in ms. Default 200; 0 turns it off
  shiftEasing?: string; // CSS easing. Default 'cubic-bezier(0.2, 0, 0, 1)'
  dropDuration?: number; // drop animation duration in ms. Default 200; 0 turns it off
  dropEasing?: string; // CSS easing. Default 'cubic-bezier(0.2, 0, 0, 1)'
}
```

`VdndAnimationConfig` is provided through `VDND_ANIMATION_CONFIG` (added in 3.2.0). See [Animations and haptics](https://gultyayev.github.io/ngx-virtual-dnd/guide/features/animations.md).

## Template contexts

```ts
// <vdnd-sortable-list> / <vdnd-virtual-scroll> itemTemplate
interface VirtualScrollItemContext<T> {
  $implicit: T;
  index: number;
  isSticky: boolean;
}

// *vdndVirtualFor
interface VirtualForContext<T> {
  $implicit: T;
  index: number;
  first: boolean;
  last: boolean;
  count: number;
}

// <vdnd-drag-preview [previewTemplate]>
interface DragPreviewContext<T = unknown> {
  $implicit: T;
  draggableId: string;
  droppableId: string;
}

// <vdnd-placeholder [template]>
interface PlaceholderContext {
  $implicit: number; // height in px
  height: number;
}
```

## Drag state

```ts
interface DraggedItem {
  draggableId: string;
  droppableId: string;
  element: HTMLElement;
  clonedElement?: HTMLElement;
  height: number;
  width: number;
  data?: unknown;
}

interface CursorPosition {
  x: number;
  y: number;
}

interface GrabOffset {
  x: number;
  y: number;
}

interface DragState {
  isDragging: boolean;
  draggedItem: DraggedItem | null;
  sourceDroppableId: string | null;
  sourceIndex: number | null;
  activeDroppableId: string | null;
  placeholderId: string | null; // deprecated: always END_OF_LIST or null, use placeholderIndex
  placeholderIndex: number | null;
  cursorPosition: CursorPosition | null;
  grabOffset: GrabOffset | null;
  initialPosition: CursorPosition | null;
  lockAxis: 'x' | 'y' | null;
  isKeyboardDrag: boolean;
  keyboardTargetIndex: number | null;
}
```

## Strategies

Virtual scroll math is pluggable. The components pick a strategy from `dynamicItemHeight`, so you only need these to build your own container.

```ts
interface VirtualScrollStrategy {
  readonly version: Signal<number>;
  getTotalHeight(itemCount: number): number;
  getFirstVisibleIndex(scrollTop: number): number;
  getVisibleCount(startIndex: number, containerHeight: number): number;
  getOffsetForIndex(index: number): number;
  getItemHeight(index: number): number;
  setMeasuredHeight(key: unknown, height: number): void;
  setItemKeys(keys: unknown[]): void;
  setExcludedIndex(index: number | null): void;
  findIndexAtOffset(offset: number): number;
  getItemCount(): number;
}
```

| Class                   | Constructor                           | Behavior                                                           |
| ----------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `FixedHeightStrategy`   | `new FixedHeightStrategy(itemHeight)` | `index * itemHeight`; the default                                  |
| `DynamicHeightStrategy` | `new DynamicHeightStrategy(estimate)` | Measured heights, prefix sums and binary search (O(log n) lookups) |

## Injection tokens

| Token                   | Provides              | Provided by                                                                  |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------- |
| `VDND_SCROLL_CONTAINER` | `VdndScrollContainer` | `VirtualViewportComponent`, `VirtualContentComponent`, `ScrollableDirective` |
| `VDND_VIRTUAL_VIEWPORT` | `VdndVirtualViewport` | `VirtualViewportComponent`, `VirtualContentComponent`                        |
| `VDND_GROUP_TOKEN`      | `VdndGroupContext`    | `DroppableGroupDirective`                                                    |
| `VDND_ANIMATION_CONFIG` | `VdndAnimationConfig` | You (opt-in), app-wide or in a component's `providers`                       |

```ts
interface VdndScrollContainer {
  readonly nativeElement: HTMLElement;
  scrollTop(): number;
  containerHeight(): number;
  scrollTo(options: ScrollToOptions): void;
}

interface VdndVirtualViewport {
  scrollTop(): number;
  containerHeight(): number;
  itemHeight(): number;
  contentOffset(): number;
  readonly nativeElement: HTMLElement;
  setRenderStartIndex(index: number): void;
  getOffsetForIndex(index: number): number;
  readonly strategy: VirtualScrollStrategy | null;
}

interface VdndGroupContext {
  readonly group: Signal<string>;
}
```

`scrollTop()` on both interfaces is the rendered scroll position, a reactive value for computing what to render. The built-in containers commit it once per animation frame, after a move of 5px or more, so it can lag the scrolling element. To compute a position (for example a scroll target), read that element's `scrollTop`. For `VirtualViewportComponent` and `ScrollableDirective` it is `nativeElement`. `VirtualContentComponent`'s host does not scroll, and its `scrollTop()` is relative to where its list starts: take the parent scroll container's element `scrollTop`, subtract the content offset, and clamp at 0.

## Constants

```ts
const END_OF_LIST = 'END_OF_LIST'; // deprecated: the value of every placeholderId; positions are indexes
const INITIAL_DRAG_STATE: DragState; // the idle state
```



---
url: https://gultyayev.github.io/ngx-virtual-dnd/changelog.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# Changelog

All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.

## [3.6.2](https://github.com/gultyayev/ngx-virtual-dnd/compare/v3.6.1...v3.6.2) (2026-10-21)

### Bug Fixes

- **lib:** autoscroll lists that grow scrollable or register mid-drag ([#152](https://github.com/gultyayev/ngx-virtual-dnd/issues/152)) ([531a9c0](https://github.com/gultyayev/ngx-virtual-dnd/commit/531a9c0b97792c60129ce718a2906d9d3686d38a))
- **lib:** claim the server's rows when vdndVirtualFor hydrates ([#153](https://github.com/gultyayev/ngx-virtual-dnd/issues/153)) ([4e759b2](https://github.com/gultyayev/ngx-virtual-dnd/commit/4e759b2acb0b49e616e978901913c4e05fbdccfe))
- **lib:** clamp keyboard targets to the list's live item count ([#149](https://github.com/gultyayev/ngx-virtual-dnd/issues/149)) ([1b3f249](https://github.com/gultyayev/ngx-virtual-dnd/commit/1b3f2491df0e97b836d8c9740a17a9f4a55f7443))
- **lib:** drop a pending press once its draggable is disabled ([#148](https://github.com/gultyayev/ngx-virtual-dnd/issues/148)) ([2e18d21](https://github.com/gultyayev/ngx-virtual-dnd/commit/2e18d21b746e60d8b9a77f4117f841c442e7e106))
- **lib:** end a drag whose draggable ID changes mid-drag ([#146](https://github.com/gultyayev/ngx-virtual-dnd/issues/146)) ([d4583ed](https://github.com/gultyayev/ngx-virtual-dnd/commit/d4583edbb88fe07b3dfe9b4745365c386ac1f8f1))
- **lib:** keep drag previews out of focus and the accessibility tree ([#151](https://github.com/gultyayev/ngx-virtual-dnd/issues/151)) ([f8f4606](https://github.com/gultyayev/ngx-virtual-dnd/commit/f8f46069941d25b86fc685a8add839e4b508eafb))
- **lib:** keep the server's row order when vdnd-virtual-scroll hydrates ([#145](https://github.com/gultyayev/ngx-virtual-dnd/issues/145)) ([8a8104b](https://github.com/gultyayev/ngx-virtual-dnd/commit/8a8104b262699434fc394b0671b7447da14ba321))
- **lib:** position and measure vdndVirtualFor rows after their check ([#147](https://github.com/gultyayev/ngx-virtual-dnd/issues/147)) ([470e1fb](https://github.com/gultyayev/ngx-virtual-dnd/commit/470e1fbe3077601861dd7d3dcdbb3b9994addb0a))
- **lib:** skip visibility-hidden droppables in pointer hit-testing ([#150](https://github.com/gultyayev/ngx-virtual-dnd/issues/150)) ([7932d58](https://github.com/gultyayev/ngx-virtual-dnd/commit/7932d58f9af5e6dace1c8f2ea4087a1c04e219d5))

## [3.6.1](https://github.com/gultyayev/ngx-virtual-dnd/compare/v3.6.0...v3.6.1) (2026-10-14)

### Bug Fixes

- **lib:** re-read the scroll offset when a scroll container is shown again ([#142](https://github.com/gultyayev/ngx-virtual-dnd/issues/142)) ([a69c4f9](https://github.com/gultyayev/ngx-virtual-dnd/commit/a69c4f9e3f139f39e08d304a5872d99e3f9e4247))

## [3.6.0](https://github.com/gultyayev/ngx-virtual-dnd/compare/v3.5.0...v3.6.0) (2026-10-08)

### Features

- **lib:** add scroll insets for sticky and overlaid content ([#139](https://github.com/gultyayev/ngx-virtual-dnd/issues/139)) ([1422e87](https://github.com/gultyayev/ngx-virtual-dnd/commit/1422e87b0955f2dd523b7d91a63121b455bb9ee1))

## [3.5.0](https://github.com/gultyayev/ngx-virtual-dnd/compare/v3.4.0...v3.5.0) (2026-10-07)

### Features

- **lib:** support lists and items inside open shadow roots ([#125](https://github.com/gultyayev/ngx-virtual-dnd/issues/125)) ([73f362c](https://github.com/gultyayev/ngx-virtual-dnd/commit/73f362cd8f886189e2af1e00e0a07909f55ae6c7))

### Bug Fixes

- **lib:** compute scrollBy() and getScrollTop() from the element's live scrollTop ([#122](https://github.com/gultyayev/ngx-virtual-dnd/issues/122)) ([3622e11](https://github.com/gultyayev/ngx-virtual-dnd/commit/3622e113358ccd7356a66b456c0ec3056651331b))
- **lib:** count wrapped rows when calculating a plain list's source index ([#137](https://github.com/gultyayev/ngx-virtual-dnd/issues/137)) ([5113cdd](https://github.com/gultyayev/ngx-virtual-dnd/commit/5113cdd892c2fd521a94dc35b8a1ab39f3c23145))
- **lib:** keep a list's scroll position after a drop into it at its bottom ([#130](https://github.com/gultyayev/ngx-virtual-dnd/issues/130)) ([b7964f5](https://github.com/gultyayev/ngx-virtual-dnd/commit/b7964f573b22a7a922026a974c1f0418fcd228f0))
- **lib:** keep a mouse drag going when another button is released ([#138](https://github.com/gultyayev/ngx-virtual-dnd/issues/138)) ([fbc53c7](https://github.com/gultyayev/ngx-virtual-dnd/commit/fbc53c71cae9d9ac16019d9c2a0c652f73cc67db))
- **lib:** keep the clone root's own placement out of the drag preview ([#124](https://github.com/gultyayev/ngx-virtual-dnd/issues/124)) ([9f04d10](https://github.com/gultyayev/ngx-virtual-dnd/commit/9f04d100b27c7eebf8f4a56aa94265cba6e2b222))
- **lib:** let a pointer drag start on a button draggable or inside a control ([#127](https://github.com/gultyayev/ngx-virtual-dnd/issues/127)) ([6d468b7](https://github.com/gultyayev/ngx-virtual-dnd/commit/6d468b791b7ab2fe94b28872e6ad8bdf0fb5c4a7))
- **lib:** open the placeholder gap and scroll a vdndVirtualFor used directly in vdndScrollable ([#129](https://github.com/gultyayev/ngx-virtual-dnd/issues/129)) ([adb78fa](https://github.com/gultyayev/ngx-virtual-dnd/commit/adb78fac4187e6f3458a08e6a028e075138f70ae))
- **lib:** report the source list in dragEnd of a draggable destroyed mid-drag ([#121](https://github.com/gultyayev/ngx-virtual-dnd/issues/121)) ([7bb5b9e](https://github.com/gultyayev/ngx-virtual-dnd/commit/7bb5b9efb344a6302378233811d58047b44b3086))
- **lib:** reveal the keyboard placeholder again after it renders at a list's end ([4c7cfda](https://github.com/gultyayev/ngx-virtual-dnd/commit/4c7cfda2b5b2ab68981eba4b13dbb3cfe7b48981)), closes [#116](https://github.com/gultyayev/ngx-virtual-dnd/issues/116)
- **lib:** skip hidden droppables in keyboard cross-list navigation ([b8bf247](https://github.com/gultyayev/ngx-virtual-dnd/commit/b8bf247cb2ffbb14dd11353e5c5158c7da7aa3f7)), closes [#113](https://github.com/gultyayev/ngx-virtual-dnd/issues/113)
- **lib:** snap a constrained drop to the list edge only once the list is scrolled there ([#128](https://github.com/gultyayev/ngx-virtual-dnd/issues/128)) ([deee3aa](https://github.com/gultyayev/ngx-virtual-dnd/commit/deee3aad8c8f3c2f8af48ac9713d1013bcd7d22c))

## [3.4.0](https://github.com/gultyayev/ngx-virtual-dnd/compare/v3.3.0...v3.4.0) (2026-10-01)

### Features

- **lib:** scope the grabbing cursor to lists and items, skip it for touch drags ([#109](https://github.com/gultyayev/ngx-virtual-dnd/issues/109)) ([8c74877](https://github.com/gultyayev/ngx-virtual-dnd/commit/8c7487722d0be4e77372076f8d35efa1c1414109))

### Performance

- **lib:** run shift animations on the compositor by animating translate ([#110](https://github.com/gultyayev/ngx-virtual-dnd/issues/110)) ([4cccdcf](https://github.com/gultyayev/ngx-virtual-dnd/commit/4cccdcfb5abab89d80a87be70d8f3a66cc800867))

## [3.3.0](https://github.com/gultyayev/angular-vdnd/compare/v3.2.1...v3.3.0) (2026-09-30)

### Features

- **lib:** recycle vdnd-virtual-scroll rows with recycleRows ([#106](https://github.com/gultyayev/angular-vdnd/issues/106)) ([8fd5f33](https://github.com/gultyayev/angular-vdnd/commit/8fd5f33b6b56c3d2e8b68e703656ca6fce351148))

### Bug Fixes

- **lib:** emit drop at release instead of from a droppable effect ([#89](https://github.com/gultyayev/angular-vdnd/issues/89)) ([dd05b62](https://github.com/gultyayev/angular-vdnd/commit/dd05b6272879a8b010905bd5e434ce94a8baf9d3))

### Performance

- **lib:** cut drag-start, per-drop and per-frame work in lists and hit-testing ([#108](https://github.com/gultyayev/angular-vdnd/issues/108)) ([afe8bc4](https://github.com/gultyayev/angular-vdnd/commit/afe8bc4ea6391daf1461b976fd10d1baa896f242))
- **lib:** find droppables through a registry instead of document queries ([#88](https://github.com/gultyayev/angular-vdnd/issues/88)) ([1e613e7](https://github.com/gultyayev/angular-vdnd/commit/1e613e710e4243ba1357526bcbddce112be99a38))
- **lib:** forward sortable list outputs without template listeners ([#100](https://github.com/gultyayev/angular-vdnd/issues/100)) ([f85a49e](https://github.com/gultyayev/angular-vdnd/commit/f85a49e42f390b7973c424118925490aae0ff2f4))
- **lib:** make the draggable touchstart listener passive when a drag delay is set ([#107](https://github.com/gultyayev/angular-vdnd/issues/107)) ([858bf29](https://github.com/gultyayev/angular-vdnd/commit/858bf29014f1b357ae32c2277ee0418ce5f2c940))
- **lib:** move the drag preview in the pointer's animation frame ([#101](https://github.com/gultyayev/angular-vdnd/issues/101)) ([4e501d9](https://github.com/gultyayev/angular-vdnd/commit/4e501d93f8855d74e5fce44150044a62bd426227))
- **lib:** render only the virtual rows whose context changed ([#99](https://github.com/gultyayev/angular-vdnd/issues/99)) ([3325a36](https://github.com/gultyayev/angular-vdnd/commit/3325a3684d8bc3ac4185b39dac4ab3b642dcda25))
- **lib:** stop re-rendering every vdnd-virtual-scroll row on placeholder moves ([#105](https://github.com/gultyayev/angular-vdnd/issues/105)) ([273081a](https://github.com/gultyayev/angular-vdnd/commit/273081aeb89331f54ed749b986389c75e00fc392))
- **lib:** update HeightCache offsets only as far as a lookup needs ([#86](https://github.com/gultyayev/angular-vdnd/issues/86)) ([dbb7632](https://github.com/gultyayev/angular-vdnd/commit/dbb763282ad46fe14a6eaac9c825392a7a1897b9))

## [3.2.1](https://github.com/gultyayev/angular-vdnd/compare/v3.2.0...v3.2.1) (2026-09-27)

### Bug Fixes

- **lib:** account for contentOffset in vdnd-virtual-viewport drops ([a46d3d3](https://github.com/gultyayev/angular-vdnd/commit/a46d3d30d0ec3899e9b9fe10ca1055ef9a9d76e2))
- **lib:** allow destroying draggables and droppables before their first render ([b42c738](https://github.com/gultyayev/angular-vdnd/commit/b42c738b0a25f0786e7ad8ef9f631922a89e5dc9))
- **lib:** cancel a pending drag-delay timer when a new press starts ([909bbff](https://github.com/gultyayev/angular-vdnd/commit/909bbffd008d2f784ddc92df1376060c974191d0))
- **lib:** cancel a pointer drag when the window loses focus ([#77](https://github.com/gultyayev/angular-vdnd/issues/77)) ([19463f2](https://github.com/gultyayev/angular-vdnd/commit/19463f276034f091a2228d79fb8b8ef3424dc2b0))
- **lib:** cancel a touch drag when the system cancels the touch ([#85](https://github.com/gultyayev/angular-vdnd/issues/85)) ([9c4f2b0](https://github.com/gultyayev/angular-vdnd/commit/9c4f2b076e5575525a8f78e6a75e296aa88779e8))
- **lib:** deprecate placeholderId, which is always END\_OF\_LIST ([#82](https://github.com/gultyayev/angular-vdnd/issues/82)) ([84c1a8b](https://github.com/gultyayev/angular-vdnd/commit/84c1a8bb881cf3bab17d496bb945c8559cd94d5b))
- **lib:** don't let a second drag replace the one in progress ([#76](https://github.com/gultyayev/angular-vdnd/issues/76)) ([73d90cb](https://github.com/gultyayev/angular-vdnd/commit/73d90cb3aab4be72001e46665d219b7da9d53ad3))
- **lib:** end the scheduler frame when a participant stops the drag ([2a1c5b4](https://github.com/gultyayev/angular-vdnd/commit/2a1c5b4d3bd083143a06415282d85cd06037b703))
- **lib:** find the droppable and draggable parents at any depth ([#79](https://github.com/gultyayev/angular-vdnd/issues/79)) ([84501ef](https://github.com/gultyayev/angular-vdnd/commit/84501efe48fbb640afad976d92bbe51966eb27be))
- **lib:** follow the finger that started a touch drag ([#78](https://github.com/gultyayev/angular-vdnd/issues/78)) ([bc5ec2d](https://github.com/gultyayev/angular-vdnd/commit/bc5ec2de4e51c8f05533e2a23dbfd3e0161078ee))
- **lib:** keep radio buttons checked when the preview clones their row ([6b4a31f](https://github.com/gultyayev/angular-vdnd/commit/6b4a31f434e80139902e3624b64c4b8a0cb0aa0e))
- **lib:** leave keyboard-drag keys to the item being dragged ([#84](https://github.com/gultyayev/angular-vdnd/issues/84)) ([12c37c6](https://github.com/gultyayev/angular-vdnd/commit/12c37c6af3ee20a023eca067eb27c3f69dd1f226))
- **lib:** let no-drag cover the elements inside it ([#75](https://github.com/gultyayev/angular-vdnd/issues/75)) ([ac97757](https://github.com/gultyayev/angular-vdnd/commit/ac977575e28c7c67b781281c493d4e5c772405fd))
- **lib:** let Space reach form controls inside a draggable ([d786f82](https://github.com/gultyayev/angular-vdnd/commit/d786f82d0334a102356a756d48a14b9b5f3284d0))
- **lib:** make reorderItems ignore a missing source item ([6f093bd](https://github.com/gultyayev/angular-vdnd/commit/6f093bd78c173bd4a7dd19e86d3c58af17866f34))
- **lib:** read the source list untracked in moveItem ([a42f34e](https://github.com/gultyayev/angular-vdnd/commit/a42f34e7f4520db339217fc5a02f2208b41749c8))
- **lib:** render and tear down on the server without browser globals ([#81](https://github.com/gultyayev/angular-vdnd/issues/81)) ([0ef9567](https://github.com/gultyayev/angular-vdnd/commit/0ef95675f5d986e9138592dc1323fb73a0d635cf))
- **lib:** render the rows in view in vdnd-virtual-viewport with a large contentOffset ([7004826](https://github.com/gultyayev/angular-vdnd/commit/7004826df28869183fdb0642477a23aa27f3adb0))
- **lib:** start and stop measuring rows when dynamicItemHeight changes ([#80](https://github.com/gultyayev/angular-vdnd/issues/80)) ([4090360](https://github.com/gultyayev/angular-vdnd/commit/40903605082af5d7dd98e6fe53a0a379e8ad2b25))
- **lib:** store the offset the browser applied in VirtualScrollContainer.scrollTo ([ea3bc1a](https://github.com/gultyayev/angular-vdnd/commit/ea3bc1aeb07fd1868f6019e109b132e26af48d9f))

## [3.2.0](https://github.com/gultyayev/angular-vdnd/compare/v3.2.0-alpha.2...v3.2.0) (2026-09-25)

## [3.2.0-alpha.2](https://github.com/gultyayev/angular-vdnd/compare/v3.2.0-alpha.1...v3.2.0-alpha.2) (2026-09-25)

### Features

- **lib:** animate the drag preview into place on drop ([#72](https://github.com/gultyayev/angular-vdnd/issues/72)) ([57186dc](https://github.com/gultyayev/angular-vdnd/commit/57186dc07a671a75c3853bf0c850a751cd5a3979))

## [3.2.0-alpha.1](https://github.com/gultyayev/angular-vdnd/compare/v3.2.0-alpha.0...v3.2.0-alpha.1) (2026-09-24)

### Features

- **docs:** add Rspress documentation site and upgrade npm to 12 ([#69](https://github.com/gultyayev/angular-vdnd/issues/69)) ([723fab1](https://github.com/gultyayev/angular-vdnd/commit/723fab1306253688b15d11c5dac8ab2001b7cf0e))

### Bug Fixes

- **lib:** end same-list keyboard navigation at the list's last slot ([a5191de](https://github.com/gultyayev/angular-vdnd/commit/a5191de55952f14fd05dd9c434cc25d1d3208c4f))
- **lib:** keep the placeholder in view during keyboard drag autoscroll ([29c0c42](https://github.com/gultyayev/angular-vdnd/commit/29c0c426f1e9d7355455b8669418284158d82a51))
- **lib:** scroll to the drop position on each keyboard move and fix the focus fallback ([abd1760](https://github.com/gultyayev/angular-vdnd/commit/abd1760ddc3811b67f5ae1ab87430f397be687a9))

## [3.2.0-alpha.0](https://github.com/gultyayev/angular-vdnd/compare/v3.1.3...v3.2.0-alpha.0) (2026-09-24)

### Features

- **lib:** add shift animation and placeholderMove event ([#68](https://github.com/gultyayev/angular-vdnd/issues/68)) ([0d697f0](https://github.com/gultyayev/angular-vdnd/commit/0d697f0f55f54e18d9e298eea388c240389c2d03))

## [3.1.3](https://github.com/gultyayev/angular-vdnd/compare/v3.1.2...v3.1.3) (2026-07-18)

### Bug Fixes

- **demo:** remove Ionic md elevation shadow from task page headers ([e22ee19](https://github.com/gultyayev/angular-vdnd/commit/e22ee19410cc215faf57c48c49674af5e5d34373))
- **e2e:** wait for stable demo layout ([#65](https://github.com/gultyayev/angular-vdnd/issues/65)) ([74e4242](https://github.com/gultyayev/angular-vdnd/commit/74e4242da76c5d1c78ea0d1e61a39997dd994f40))
- gate perf by measuring base and head on the same runner ([#63](https://github.com/gultyayev/angular-vdnd/issues/63)) ([62d314f](https://github.com/gultyayev/angular-vdnd/commit/62d314f5c471a9269dbe6c5cc661d2695c78a3ea))
- **lib:** exclude disabled droppables from drag-time candidate sets ([#51](https://github.com/gultyayev/angular-vdnd/issues/51)) ([0efb3ec](https://github.com/gultyayev/angular-vdnd/commit/0efb3ec740c3536c1d05e7a72f2e4ddd0f4d3a7b))
- **lib:** fall through exhausted nested containers in autoscroll ([#60](https://github.com/gultyayev/angular-vdnd/issues/60)) ([38eee56](https://github.com/gultyayev/angular-vdnd/commit/38eee565d5c46e85dda1b880a8904c125653b574))
- **lib:** make autoscroll registration resilient to post-init layout changes ([#61](https://github.com/gultyayev/angular-vdnd/issues/61)) ([c71c51c](https://github.com/gultyayev/angular-vdnd/commit/c71c51c5ade6a535216149e05e37e0222bdbfbed))
- **lib:** normalize keyboard drag end index ([#45](https://github.com/gultyayev/angular-vdnd/issues/45)) ([4f54b8f](https://github.com/gultyayev/angular-vdnd/commit/4f54b8ffb85ccd331e150a8c7f19139b68f6060d))
- **lib:** preserve source index across rapid cross-list drags ([#44](https://github.com/gultyayev/angular-vdnd/issues/44)) ([6695753](https://github.com/gultyayev/angular-vdnd/commit/6695753c3691930ea1a880a58a7fe128abefa4cc))
- **lib:** refresh drag hit-test candidates on mid-drag DOM changes ([#58](https://github.com/gultyayev/angular-vdnd/issues/58)) ([b9d21d7](https://github.com/gultyayev/angular-vdnd/commit/b9d21d7bd8c8bed754627c0cb4e0ccd212e70303))
- **lib:** route keyboard cross-list count through DragIndexCalculatorService ([#59](https://github.com/gultyayev/angular-vdnd/issues/59)) ([a2bd956](https://github.com/gultyayev/angular-vdnd/commit/a2bd95678b48c04bd2447ed62a6f131a460f6b81))
- make performance regression gate reliable ([#52](https://github.com/gultyayev/angular-vdnd/issues/52)) ([061828c](https://github.com/gultyayev/angular-vdnd/commit/061828c7402e5f769fa42d92428d2f51c808bf7b))

### Performance

- **lib:** stop active droppable effect from re-snapshotting every frame ([#62](https://github.com/gultyayev/angular-vdnd/issues/62)) ([b2acd8a](https://github.com/gultyayev/angular-vdnd/commit/b2acd8a3212411151d575d976b26ef0afb40a5d4))

## [3.1.2](https://github.com/gultyayev/angular-vdnd/compare/v3.1.1...v3.1.2) (2026-07-07)

### Bug Fixes

- **lib:** refresh viewport transforms on drag exclusion changes ([2057a38](https://github.com/gultyayev/angular-vdnd/commit/2057a387398dc5b3ff02b4a3c2fff42d39e4acf9))
- **lib:** safely resolve consumer IDs in attribute lookups ([ab2ea17](https://github.com/gultyayev/angular-vdnd/commit/ab2ea17091ba7ff883c4a55518a60434c5861461))
- **lib:** sync auto-scroll registration with signal inputs ([c084a32](https://github.com/gultyayev/angular-vdnd/commit/c084a32aa458326a8a684e17270c3ab4c5bf50f9))

## [3.1.1](https://github.com/gultyayev/angular-vdnd/compare/v3.1.0...v3.1.1) (2026-06-24)

### Performance

- **lib:** drag-and-drop hot-path optimizations ([#18](https://github.com/gultyayev/angular-vdnd/issues/18)) ([7f07562](https://github.com/gultyayev/angular-vdnd/commit/7f075621c78886ae1ced105f3835b2844c11cb5b))

## [3.1.0](https://github.com/gultyayev/angular-vdnd/compare/v3.0.1...v3.1.0) (2026-06-23)

### Features

- **lib:** allow Angular 22 in peer dependency range ([40db308](https://github.com/gultyayev/angular-vdnd/commit/40db3087867e44bd0698c7940bd278e44135549f))

## [3.0.1](https://github.com/gultyayev/angular-vdnd/compare/v3.0.0...v3.0.1) (2026-03-05)

### Performance

- **lib:** cache droppable metadata during active drag ([53f9c59](https://github.com/gultyayev/angular-vdnd/commit/53f9c59fd231172cdfe120113dc7abaf320895d7))
- **lib:** optimize hot-path services for active drag ([6be81b4](https://github.com/gultyayev/angular-vdnd/commit/6be81b4ce4fbd088b9ca739b0058be182973afbc))

## [3.0.0](https://github.com/gultyayev/angular-vdnd/compare/v2.0.0...v3.0.0) (2026-02-20)

### ⚠ BREAKING CHANGES

- **lib:** dragMove, dragReadyChange, dragEnter, dragLeave,
  dragOver, visibleRangeChange, and scrollPositionChange outputs have
  been removed along with their associated event types. Use
  DragStateService signals for equivalent reactive state, and the
  vdnd-drag-pending CSS class instead of dragReadyChange.

### Features

- **lib:** remove 7 unused outputs from public API ([ff680d8](https://github.com/gultyayev/angular-vdnd/commit/ff680d82183e4e95e6b3f61cc3940d8c7962eca8))

### Bug Fixes

- **lib:** clamp constrainToContainer to scroll viewport and fix flaky E2E reorder ([2ac1bd6](https://github.com/gultyayev/angular-vdnd/commit/2ac1bd673f10435b05b7613883b87e2317d89412))

## [2.0.0](https://github.com/gultyayev/angular-vdnd/compare/v2.0.0-alpha.1...v2.0.0) (2026-02-17)

## [2.0.0-alpha.1](https://github.com/gultyayev/angular-vdnd/compare/v2.0.0-alpha.0...v2.0.0-alpha.1) (2026-02-14)

### Performance

- **lib:** split high-frequency signals from monolithic drag state ([18d642f](https://github.com/gultyayev/angular-vdnd/commit/18d642f880461f4c59d5252ab1eee1b8c0bbc506))

## [2.0.0-alpha.0](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.6...v2.0.0-alpha.0) (2026-02-13)

### ⚠ BREAKING CHANGES

- **lib:** VirtualContentComponent template restructured — virtual
  area is now wrapped in a `.vdnd-virtual-area` div. Consumers using
  `contentOffset` are unaffected (it remains as an escape hatch).
- **lib:** `totalItems` input removed from `VirtualViewportComponent`
  and `VirtualContentComponent`. The total item count is now derived
  automatically from the child `VirtualForDirective` via the shared strategy.

DX improvements:

- `*vdndVirtualFor` inherits `itemHeight`, `dynamicItemHeight`, and
  `droppableId` from parent viewport/droppable when inside one — only
  `trackBy` remains required on the directive
- `VirtualSortableListComponent.group` is now optional — inherits from
  parent `vdndGroup` directive
- `FixedHeightStrategy.setItemKeys()` now bumps `version` on count change,
  enabling strategy-derived total height
- `VirtualScrollStrategy.getItemCount()` is now a required interface method

Migration: Remove `[totalItems]` bindings from `vdnd-virtual-viewport` and
`vdnd-virtual-content`. Remove redundant `itemHeight`, `dynamicItemHeight`,
and `droppableId` from `*vdndVirtualFor` when inside a viewport component.

### Features

- **lib:** auto-measure projected header height via ContentHeaderDirective ([b94b634](https://github.com/gultyayev/angular-vdnd/commit/b94b6345f2d0f8e2da861ed72d9e7cc6e40ac73f))
- **lib:** eliminate data duplication in Pattern B consumer API ([2745934](https://github.com/gultyayev/angular-vdnd/commit/2745934ea1280f17ca7c01c622ec7409a5f789e0))

### Bug Fixes

- **lib:** unify constrained mode probe logic with capped center ([9e20230](https://github.com/gultyayev/angular-vdnd/commit/9e20230df4d1870787660579f123c0bfb6432eb5))

## [1.3.0-alpha.6](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.5...v1.3.0-alpha.6) (2026-02-13)

### Bug Fixes

- **lib:** dynamic height drift cases ([916d97e](https://github.com/gultyayev/angular-vdnd/commit/916d97eded0261ccb135daafc3b4d0b0b56cc29b))

## [1.3.0-alpha.5](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.4...v1.3.0-alpha.5) (2026-02-13)

### Bug Fixes

- **lib:** harden dynamic height strategy performance and correctness ([9caac28](https://github.com/gultyayev/angular-vdnd/commit/9caac28ecd32fe8c9d41d4cd3098bd1a59a29a08))
- **lib:** use direction-aware probing for dynamic drag index ([b6346d1](https://github.com/gultyayev/angular-vdnd/commit/b6346d1113b733dc6fd94f5cfa8e5dbf7b13152b))

## [1.3.0-alpha.4](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.3...v1.3.0-alpha.4) (2026-02-13)

### Bug Fixes

- **lib:** allow constrained dynamic drag to reach list edges ([38519b2](https://github.com/gultyayev/angular-vdnd/commit/38519b27648d1d8c8de6d0f50f2af55b5dea5da4))

## [1.3.0-alpha.3](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.2...v1.3.0-alpha.3) (2026-02-13)

### Features

- **lib:** warn of trackBy duplicates ([087f77d](https://github.com/gultyayev/angular-vdnd/commit/087f77de697854e0f7cd96431c65a4bb491f4a27))

## [1.3.0-alpha.2](https://github.com/gultyayev/angular-vdnd/compare/v1.2.3...v1.3.0-alpha.2) (2026-02-13)

### Features

- **lib:** add dynamic item height support for virtual scroll ([#15](https://github.com/gultyayev/angular-vdnd/issues/15)) ([a7479e3](https://github.com/gultyayev/angular-vdnd/commit/a7479e38671b8269b897fa56f781a7182609e150))
- **lib:** constrain drag by container ([#16](https://github.com/gultyayev/angular-vdnd/issues/16)) ([2fe954f](https://github.com/gultyayev/angular-vdnd/commit/2fe954f4b2cc3f92929bad01df679b7692243197))

### Bug Fixes

- **lib:** don't print warnings in prod mode ([d987c96](https://github.com/gultyayev/angular-vdnd/commit/d987c96bbd98c8ae0a5d94c9668d02a6e06f7792))
- **lib:** stabilize same-list dynamic placeholder index before exclusion sync ([fe6063d](https://github.com/gultyayev/angular-vdnd/commit/fe6063dc77cdc8db02e5ca814d78daf23fe4854c))

## [1.3.0-alpha.1](https://github.com/gultyayev/angular-vdnd/compare/v1.3.0-alpha.0...v1.3.0-alpha.1) (2026-02-12)

### Bug Fixes

- fix e2e ([0d9e468](https://github.com/gultyayev/angular-vdnd/commit/0d9e4684d31c27cc8daaf8f70999c8750c9ddea6))
- fix gaps ([2b352ec](https://github.com/gultyayev/angular-vdnd/commit/2b352ec982e8e9f1c8c1de08c35b393b87c8b518))
- fix height shrinkage ([d9030e5](https://github.com/gultyayev/angular-vdnd/commit/d9030e5a7fd5707f9db8a3ade90aa6293c8f9b68))

## [1.3.0-alpha.0](https://github.com/gultyayev/angular-vdnd/compare/v1.2.3...v1.3.0-alpha.0) (2026-02-11)

### Features

- **lib:** add dynamic item height support for virtual scroll ([5678c3c](https://github.com/gultyayev/angular-vdnd/commit/5678c3c3fa60b5202c77a2c1c3f8b0c08528b7ae))

### Bug Fixes

- **lib:** don't print warnings in prod mode ([d987c96](https://github.com/gultyayev/angular-vdnd/commit/d987c96bbd98c8ae0a5d94c9668d02a6e06f7792))
- **lib:** fix scroll with drag in dynamic height ([871f9b4](https://github.com/gultyayev/angular-vdnd/commit/871f9b4e99bfd7b1c40264506e38eb9517cbcfb2))

## [1.2.3](https://github.com/gultyayev/angular-vdnd/compare/v1.2.2...v1.2.3) (2026-02-06)

### Bug Fixes

- **lib:** teleport drag preview to body overlay to fix CSS transform offset ([979c443](https://github.com/gultyayev/angular-vdnd/commit/979c44372b1b6e4c93c48567ac06515b2a01409f))

## [1.2.2](https://github.com/gultyayev/angular-vdnd/compare/v1.2.1...v1.2.2) (2026-01-24)

### Performance

- **lib:** reduce drag jank and dedupe scroll bindings ([#9](https://github.com/gultyayev/angular-vdnd/issues/9)) ([52b0177](https://github.com/gultyayev/angular-vdnd/commit/52b01773113ed05db9dfc1820f2882454c7467f6))

## [1.2.1](https://github.com/gultyayev/angular-vdnd/compare/v1.2.0...v1.2.1) (2026-01-23)

### Bug Fixes

- **lib:** prevent axis-lock offset at drag start ([#7](https://github.com/gultyayev/angular-vdnd/issues/7)) ([3cf1611](https://github.com/gultyayev/angular-vdnd/commit/3cf161114912676b45414f197bc15a4c7de1e756))

### Performance

- **lib:** use transform-based positioning for drag preview ([#5](https://github.com/gultyayev/angular-vdnd/issues/5)) ([fcd8c75](https://github.com/gultyayev/angular-vdnd/commit/fcd8c758ad920a0a4e1a19acd27a90797c906d29))

## [1.2.0](https://github.com/gultyayev/angular-vdnd/compare/v1.1.2...v1.2.0) (2026-01-23)

### Features

- **demo:** add page-level scroll demo with Ionic ([#4](https://github.com/gultyayev/angular-vdnd/issues/4)) ([d1c7fb1](https://github.com/gultyayev/angular-vdnd/commit/d1c7fb18c5b6b5903b929b13e533452198d36af8))

## [1.1.2](https://github.com/gultyayev/angular-vdnd/compare/v1.1.1...v1.1.2) (2026-01-14)

### Performance

- **lib:** optimize change detection and reduce allocations during drag ([1b8a579](https://github.com/gultyayev/angular-vdnd/commit/1b8a5791aa36010c95a11fc72dcf4aed03e987d2))

## [1.1.1](https://github.com/gultyayev/angular-vdnd/compare/v1.1.0...v1.1.1) (2026-01-08)

## [1.1.0](https://github.com/gultyayev/angular-vdnd/compare/v1.0.0...v1.1.0) (2026-01-08)

### Features

- **lib:** add a11y support ([3ebccec](https://github.com/gultyayev/angular-vdnd/commit/3ebccec10d447e9840168d0a1e97a5a5039188ed))



---
url: https://gultyayev.github.io/ngx-virtual-dnd/index.md
---

> For AI agents: the complete documentation index is available at https://gultyayev.github.io/ngx-virtual-dnd/llms.txt, the full documentation bundle is available at https://gultyayev.github.io/ngx-virtual-dnd/llms-full.txt.

# ngx-virtual-dnd

Drag and drop for virtual scrolling

> Sortable lists and boards for Angular that stay fast with thousands of items. Only the visible rows are rendered, and drag and drop still works across all of them.

[Get started](/guide/start/introduction) | [Live demo](https://gultyayev.github.io/ngx-virtual-dnd/demo/)

## Features

- **Built for virtual lists**: Hit-testing and drop positions are computed from geometry, not from sibling DOM nodes, so drops land correctly on rows that are not rendered.
- **Dynamic item heights**: Rows are measured with ResizeObserver and cached by ID. Lookups use prefix sums and binary search.
- **Multiple lists**: Move items between any lists in the same group, with edge auto-scroll while dragging.
- **Keyboard and touch**: Space to pick up, arrow keys to move, Escape to cancel. Touch drags support a hold delay so lists still scroll.
- **Signals first**: Standalone components and directives for Angular 21 and 22. Drop events plus small helpers update your signal-based state.
- **Guides for AI assistants**: An installable agent skill and llms.txt give coding assistants the same guidance as these docs.

Quick look


## A sortable list of 1,000 rows in one template
Only the rows on screen are in the DOM. Drops arrive as events, and a helper applies them to your signal.
1. **Install the package** No providers and no global stylesheet to register.
2. **Put rows and lists in a group** Declare the row template inside a `vdndGroup` element so every draggable finds its group.
3. **Apply the drop** The library never changes your data. `reorderItems()` applies the move to your signal.
[Read the quick start →](https://gultyayev.github.io/ngx-virtual-dnd/guide/start/quick-start.md)

```angular-html title="template.html" {13}
<div vdndGroup="tasks">
  <ng-template #taskTpl let-task>
    <div class="row" [vdndDraggable]="task.id">{{ task.title }}</div>
  </ng-template>

  <vdnd-sortable-list
    droppableId="backlog"
    [items]="tasks()"
    [itemHeight]="48"
    [containerHeight]="336"
    [itemIdFn]="taskId"
    [itemTemplate]="taskTpl"
    (drop)="onDrop($event)"
  />
</div>

<vdnd-drag-preview />
```
```ts title="quick-start.ts" {9}
export class QuickStartExampleComponent {
  readonly tasks = signal<Task[]>(
    Array.from({ length: 1000 }, (_, i) => ({ id: `task-${i + 1}`, title: `Task ${i + 1}` })),
  );

  readonly taskId = (task: Task): string => task.id;

  onDrop(event: DropEvent): void {
    reorderItems(event, this.tasks);
  }
}
```