Dnd Sort - Web

For development, import DndSort from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

Drag Handle
Drag Handle Button
Draggable Card
Sort Line
Drag Ghost
Drag Preview
Drop Zone

Options

Draggable Card

Besides the handle, the Draggle Card’s content is highly customizable. Draggable Card can use many of the features of the base Card component.

Draggable Target

Where a user can grab a Card is configurable to the whole card or only on the drag handle.

Whole Card

Use the whole Card as a draggable region when:

Users do NOT need to select the text of the Card
D&D is a major feature of the content
Outside of an overflow menu, other inner Card actions are not present

Drag handle only

Use the Drag Handle only as the draggable region when:

A user should be able to select the text of the Card
The Card is very large
There are other, non-overflow menu actions a user can take in the Card. This could be something as simple as a Checkbox.

Drag Preview

Drag Previews, what is displayed while dragging, can be customized.

Drop Zone

Sort Line

Behavior

Drag handle alignment

The drag handle is always top-aligned in the Draggable Card. The rest of the card content can be vertically aligned as desired.

Accessibility

Provide alternatives to Drag and Drop

While Dnd Sort is keyboard navigable, it is still preferable that users have alternatives to using drag and drop functionality to complete a task.

Usage Guidelines

Standard	Requirement
DoSorting a list	Sorting a vertical or horizontal list of items.
DoBucketing items	Bucketing and sorting items, such as a kanban UI.
DoUse the provided drag-handle icon	Use the base `Dnd.Handle` icon for drag and drop; see How to Use.
DoUse the default Drop Zone and sort line styles	Use the provided default styles of Drop Zone and sort line; see How to Use.
Don’tNon-standard drag and drop scenarios	Dnd Sort only covers a handful of drag and drop scenarios. Don’t force alternative scenarios to use this approach — use the individual components found in Dnd to assemble a custom scenario instead.
Don’tAlternative drag-handle icons	Avoid using alternative icons for drag and drop; see How to Use.
Don’tSimplified drag-and-drop styling	Avoid simplifying the styling of drag and drop — the default styling provides clarity on where a user can drop in a complicated app; see How to Use.

Examples of DND Sort

Sorting a List

Sorting a list is the primary usage of Dnd Sort. This can be done vertically and horizontally.

Kanban-style sort

Also known as bucketing. Note that the Card containers & text are not explicitly part of the Dnd Sort component.

Dashboard-type arrangements

How to Use

Use the base configurations of icons, drop zones

How to Use

Use the base configurations of icons, drop zones

Code

Implementation
DndSort Props
DndSort.Card Props
DndSort.Zone Props
DndSortChangeEvent

Common Examples

Bucketing

DndSort is a great way to create a drag-and-drop interface for moving items between different buckets.

Sorting a list

DndSort is also a great way to create a drag-and-drop interface for sorting a list of items.

Bucket and sort

DndSort can also be used to create a drag-and-drop interface for moving items between different buckets and sorting them within those buckets.Note this example also demonstrates cards initially beginning outside of the buckets.

Validation

DndSort provides ways to validate the drag-and-drop interaction. This is useful for preventing invalid interactions, such as moving an item to a bucket that does not accept it.

Basic Validation

The simplest way to validate is to use the type prop on the DndSort.Card component in conjunction with acceptedTypes prop on the DndSort.Zone component.

<DndSort.Zone acceptedTypes={["fruit"]}>
  <DndSort.Card type="fruit">🍎 Apple</DndSort.Card>
</DndSort.Zone>

Advanced Validation

A more advanced way to validate is to use the validator prop on the DndSort.Zone component. This prop takes a function which receives the item id. The function should return a boolean indicating whether the drop is valid. Here are some examples of how to use the validator prop:

// Limit the zone to only accept items with ids in an allowed list
const validator = (id) => validIds.includes(id);
<DndSort.Zone validator={validator}></DndSort.Zone>;

// Limit the based on a property of the item
const validator = (id) => people[id].isFriendly;
<DndSort.Zone validator={validator}></DndSort.Zone>;

// Limit the number of items in a zone to 5
const validator = () => zoneItems.length <= 5;
<DndSort.Zone validator={validator}></DndSort.Zone>;

Customization

DndSort provides a number of ways to customize the drag-and-drop interaction. This includes customizing the appearance of the items and zones.

Advanced zone rendering

The advancedRenderer prop of DndSort.Zone is an alternative to children, allowing you to customize the appearance of the drop zone based upon its internal state.This allows you to show different content when a drag is happening, when an item is over the drop zone, or if the dragged item is valid/invalid for the drop zone.

Custom card preview rendering

The previewRenderer prop of DndSort.Card offers a means to customize the appearance of the card when it is being dragged. This is useful for showing a different appearance for the card, such as a simpler version of a complex card.

Interactive Children

By default, the DndSort.Card places a button around the entire card. This is optimal for accessibility. But if you want to place interactive elements inside your card, it harms accessibility. To resolve this issue, set dragOnlyWithHandle on the DndSort.Card if your card has interactive elements.

Anti-Patterns

Nesting

DndSort does not support nesting. i.e. you may not use a zone as an item.This is an intentional design decision to guarantee these components meet our accessibility and usability standards.If you have a use case that requires nesting, please reach out to us. We would love to hear about your use case and help you find a solution.

Best Practices

dragOnlyWithHandle

<DndSort.Card dragOnlyWithHandle>
  <Button />
</DndSort.Card>

Use the dragOnlyWithHandle prop if your card contains interactive elements.

<DndSort.Card>
  <Button />
</DndSort.Card>

Don’t

Don’t use interactive elements in cards without dragOnlyWithHandle.

import { DndSort } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<DndSort onDrop={(event) => console.log(event)}>
  {/* DndSort.Zone and DndSort.Card components */}
</DndSort>
); }

`DndSort` Props

DndSort is the root component that must wrap DndSort sub-components. It provides the context and internal logic for the drag-and-drop interaction.

React.ReactNode

Various children elements including DndSort.Zone and DndSort.Card.

(DndSortChangeEvent) => void

Callback function fired when an item is dropped.

import { DndSort } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <DndSort.Card
      id="card-1"
      label="Card 1"
      dragOnlyWithHandle={false}
    >
      Card content
    </DndSort.Card>
  );
}

`DndSort.Card` Props

DndSort.Card is a component that represents a card that can be dragged and dropped. It uses Card internally and most of the props are forwarded to the Card.

string | number

required

The unique identifier for the card.

string

required

The label for the card, used for accessibility.

React.ReactNode

The content of the card.

boolean

default:"false"

If true, the card can only be dragged when the drag handle is used. If false, the card can be dragged by any part of it.

(DndSortChangeEvent) => void

Callback function to be called when the card is dropped. Same as onDrop on the DndSort component.

({ valid }) => React.ReactNode

Advanced. A function that returns a React node to be used as the preview renderer.

string

The type of the card, used for validation (optional).

import { DndSort } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<DndSort.Zone
  id="zone-1"
  label="Zone 1"
  sortable={false}
  orientation="vertical"
>
  {/* Zone content */}
</DndSort.Zone>
); }

`DndSort.Zone` Props

DndSort.Zone is a component that represents a drop zone where items can be dropped. It may either be sortable or non-sortable. Only the basic styling is applied to the zone (i.e. border and background during a drag-and-drop interaction). Props are forwarded to the underlying div element, so you can provide styles, className, and other props to customize the appearance of the zone.

string | number

required

The unique identifier for the zone.

string

required

The label for the zone, used for accessibility.

string[]

An array of accepted types for this zone. If not provided, all types are accepted. Compares against the type prop of the card.

({ isDragging, isOver, isValid }) => React.ReactNode

Advanced. A function to render the drop zone using internal state parameters.

React.ReactNode

The contents of the zone.

"start" | "end"

default:"end"

The default position where items will be dropped if dropped directly onto the zone.

GapSize

default:"4"

The gap between items in the zone. See Flex for more info. Important for sortable zones to maintain enough space for the sort line.

"horizontal" | "vertical"

default:"vertical"

The orientation of the items in the zone.

boolean

default:"false"

If true, the zone is sortable. If false, the zone is not sortable.

(string | number)[]

default:"[]"

Required if sortable. An array of sorted IDs for the items in the zone, must match render order.

(id) => boolean

A function to validate the drop action. Given an item’s id, this function must return true for valid drops, false for invalid drops.

DndSortChangeEvent

string | number

The ID of the draggable item that was dropped.

string | number | null

The ID of the previous drop zone where the item was located before being dropped. This can be null if the item is coming from outside of any zone.

"(string" | "number)[]" | "null"

An array representing the sort order of items in the previous drop zone before the drop. This can be used to update the order of items in the previous zone. This value is null if the previous drop zone (if any) was not sortable.

boolean

Indicates whether the drop was valid based on the accepted types and custom validation.

string | number | null

The ID of the drop zone where the item was dropped. This can be null if the item was not dropped in a zone.

"(string" | "number)[]" | "null"

An array representing the sort order of items in the drop zone after the drop. This can be used to update the order of items in the zone. This value is null if the target drop zone (if any) is not sortable.

​Anatomy

​Options

​Draggable Card

​Draggable Target

​Whole Card

​Drag handle only

​Drag Preview

​Drop Zone

​Sort Line

​Behavior

​Drag handle alignment

​Accessibility

​Provide alternatives to Drag and Drop

​Usage Guidelines

​Examples of DND Sort

​Sorting a List

​Kanban-style sort

​Dashboard-type arrangements

​How to Use

​How to Use

​Code

​Common Examples

​Bucketing

​Sorting a list

​Bucket and sort

​Validation

​Basic Validation

​Advanced Validation

​Customization

​Advanced zone rendering

​Custom card preview rendering

​Interactive Children

​Anti-Patterns

​Nesting

​Best Practices

​dragOnlyWithHandle

​DndSort Props

​DndSort.Card Props

​DndSort.Zone Props

​DndSortChangeEvent

Anatomy

Options

Draggable Card

Draggable Target

Whole Card

Drag handle only

Drag Preview

Drop Zone

Sort Line

Behavior

Drag handle alignment

Accessibility

Provide alternatives to Drag and Drop

Usage Guidelines

Examples of DND Sort

Sorting a List

Kanban-style sort

Dashboard-type arrangements

How to Use

How to Use

Code

Common Examples

Bucketing

Sorting a list

Bucket and sort

Validation

Basic Validation

Advanced Validation

Customization

Advanced zone rendering

Custom card preview rendering

Interactive Children

Anti-Patterns

Nesting

Best Practices

dragOnlyWithHandle

`DndSort` Props

`DndSort.Card` Props

`DndSort.Zone` Props

DndSortChangeEvent