Skip to main content

Drag Source

Overview​

The Drag Source Model defines the core types and utilities used for working with draggable elements that exist outside of a drop-zone.

These types help enforce structure on drag sources, provide type safety, and include helper functions to validate and mark data as draggable.

DragState​

export type DragState = 'idle' | 'is-dragging' | 'preview' | 'is-dragging-over';

Represents the possible states of a draggable item during drag-and-drop:

  • idle: The item is not being dragged.

  • is-dragging: The item is actively being dragged.

  • preview: The item is shown as a preview before dropping.

  • is-dragging-over: The item is being dragged over a valid drop-zone.

DragSourceData<TType>​

export type DragSourceData<TType> = {
  type: TType;
  imageUrl?: string;
};

The base type for drag source items.

  • type: The identifier used to classify the draggable item.

  • imageUrl?: Optional image path to visually represent the item.

Extending DragSourceData<TType>

You can freely extend DragSourceData to include custom fields (e.g., labels, colors). This keeps your drag source items flexible while remaining type-safe.

// Extend base drag source data with extra fields
export type CustomDraggable = TDraggableData<'file'> & {
  label: string;
  size: number;
  color?: string;
};

DragSourceItem<T>​

export type DragSourceItem<T extends DragSourceData<any>> = T & {
  [dragSourceKey]: true;
};

An extended type of DragSourceData which includes an internal marker key (__dragSource__). This ensures that an object is recognized as a valid drag source item by the utilities in this model.

Helper Functions​

getDragSourceItem​

export function getDragSourceItem<T extends DragSourceData<any>>(item: T): DragSourceItem<T>

Marks a given item as a drag source by attaching a hidden property (__dragSource__). This makes the object compatible with drag-and-drop logic.

Example​

const rawItem = { type: 'widget', imageUrl: 'url path' };
const dragSource = getDragSourceItem(rawItem);

// dragSource is now typed as DragSourceItem<{ type: 'widget'; imageUrl: string }>

isDragSourceItem​

export function isDragSourceItem<T extends DragSourceData<any> = DragSourceData<any>>(
  data: Record<string | symbol, unknown>
): data is T

Type guard that checks if a given object is a valid DragSourceItem.

Example​

if (isDragSourceItem(someData)) {
  console.log(someData.type); // safely typed
}

See Also​