> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dnd Sort – Design
> Dnd Sort is a collection of components built for the purpose of solving bucketing and sorting, two very common applications of the drag-and-drop interaction.
export const LiveCode = ({children, customHeight, clickToLoad, example, fullWidth, fullHeight, hideCodeInLiveCode, screenshot, screenshotOnly, showCode: showCodeProp}) => {
const SCREENSHOTS_BASE = "https://servicetitan.github.io/anvil2-docs-live-code/screenshots";
const STACKBLITZ_BASE = "https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples";
const [showCodeBlock, setShowCodeBlock] = useState(showCodeProp ?? false);
const [isLocalOverride, setIsLocalOverride] = useState(false);
useEffect(() => {
const examplePath = `/images/live-code-screenshots-tmp/${example}.png`;
fetch(examplePath, {
method: "HEAD"
}).then(r => {
if (r.ok) setIsLocalOverride(true);
}).catch(() => {});
}, [example]);
const screenshotBase = isLocalOverride ? "/images/live-code-screenshots-tmp" : SCREENSHOTS_BASE;
if (screenshotOnly) {
return
1. Drag Handle
2. Drag Handle Button
3. Draggable Card
4. Sort Line
5. Drag Ghost
6. Drag Preview
7. 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.
```tsx lines theme={null}
import { useState } from "react";
import { DndSort } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
type Order = (string | number)[];
const teams: Items = {
A: { name: "Card Content", type: "item" },
};
function App() {
const [order, _setOrder] = useState(["A"]);
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
### Draggable Target
Where a user can grab a Card is configurable to the whole card or only on the drag handle.
#### Whole Card
```tsx lines theme={null}
import { useState } from "react";
import { DndSort, type DndSortChangeEvent } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
const teams: Items = {
A: { name: "Whole Card Target #1", type: "item" },
B: { name: "Whole Card Target #2", type: "item" },
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [order, setOrder] = useState<(string | number)[]>(["A", "B"]);
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setOrder((previousOrder) => event.zoneSort || previousOrder);
};
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
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
```tsx lines theme={null}
import { useState } from "react";
import { DndSort, type DndSortChangeEvent } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
type Order = (string | number)[];
const teams: Items = {
A: { name: "Drag Handle Only Target #1", type: "item" },
B: { name: "Drag Handle Only Target #2", type: "item" },
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [order, setOrder] = useState(["A", "B"]);
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setOrder((previousOrder) => event.zoneSort || previousOrder);
};
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
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.
```tsx lines theme={null}
import { useState } from "react";
import {
DndSort,
Card,
Flex,
Avatar,
Text,
Chip,
type DndSortChangeEvent,
} from "@servicetitan/anvil2";
type Order = (string | number)[];
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [order, setOrder] = useState(["A", "B", "C"]);
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setOrder((previousOrder) => event.zoneSort || previousOrder);
};
return (
No custom drag preview
Small drag preview}
>
Small drag preview
(
Maximilian the Magnificent
Director of Plumber Operations
)}
>
Highly custom preview
);
}
export default App;
```
### Drop Zone
```tsx lines theme={null}
import { Flex, Dnd } from "@servicetitan/anvil2";
function App() {
return (
Resting Drop Zone
Visible Drop Zone while dragging
Valid Drop Zone, user is over the Drop Zone
Invalid drop zone, user is over the Drop Zone
);
}
export default App;
```
### Sort Line
```tsx lines theme={null}
import { Dnd } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
```tsx lines theme={null}
import { Dnd } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
## 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.
```tsx lines theme={null}
import { useState } from "react";
import { DndSort } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
type Order = (string | number)[];
const teams: Items = {
A: {
name: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus semper vitae metus ut venenatis. Morbi commodo ante nec faucibus porta. Etiam dignissim neque id libero mollis pretium. Cras vitae mattis mauris. Ut ut enim porta, blandit nibh et, finibus massa. Ut tincidunt nibh risus, et dictum felis tristique non.",
type: "item",
},
};
function App() {
const [order, _setOrder] = useState(["A"]);
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
## 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.
## When to use
Dnd Sort is a collection used for a few sub-categories of possible Drag and Drop scenarios. Such situations include:
* Sorting a vertical or horizontal list of items
* Bucketing and sorting items, such as a kanban UI.
### When not to use
Dnd Sort only covers a handful of drag and drop scenarios, alternative scenarios should not be forced to use this approach. In such cases, use the individual components found in Dnd to assemble your custom scenario.
### Examples of DND Sort
#### Sorting a List
Sorting a list is the primary usage of Dnd Sort. This can be done vertically and horizontally.
```tsx lines theme={null}
import { useState } from "react";
import { DndSort, type DndSortChangeEvent } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
type Order = (string | number)[];
const teams: Items = {
A: { name: "Card of List #1", type: "item" },
B: { name: "Card of List #2", type: "item" },
C: { name: "Card of List #3", type: "item" },
D: { name: "Card of List #4", type: "item" },
E: { name: "Card of List #5", type: "item" },
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [order, setOrder] = useState(["A", "B", "C", "D", "E"]);
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setOrder((previousOrder) => event.zoneSort || previousOrder);
};
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
```tsx lines theme={null}
import { useState } from "react";
import { DndSort, type DndSortChangeEvent } from "@servicetitan/anvil2";
type Items = {
[key: string | number]: { name: string; type: string };
};
type Order = (string | number)[];
const teams: Items = {
A: { name: "Card #1", type: "item" },
B: { name: "Card #2", type: "item" },
C: { name: "Card #3", type: "item" },
D: { name: "Card #4", type: "item" },
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [order, setOrder] = useState(["A", "B", "C", "D"]);
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setOrder((previousOrder) => event.zoneSort || previousOrder);
};
return (
{order.map((itemId) => (
{teams[itemId].name}
))}
);
}
export default App;
```
#### Kanban-style sort
Also known as bucketing. Note that the Card containers & text are not explicitly part of the Dnd Sort component.
```tsx lines theme={null}
import { useState } from "react";
import {
DndSort,
Flex,
Grid,
Card,
Text,
type DndSortChangeEvent,
} from "@servicetitan/anvil2";
type Buckets = {
[key: string]: (string | number)[];
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [buckets, setBuckets] = useState({
"zone-1": ["A", "B", "C"],
"zone-2": ["D", "E"],
"zone-3": ["F"],
});
const someStylesOfYourChoosing = {
flexDirection: "column",
width: "100%",
borderRadius: "12px",
} as const;
const handleDrop = (event: DndSortChangeEvent) => {
setMostRecentEvent(event);
setBuckets((prevBuckets) => {
// If the item wasn't dropped in a zone, do nothing
if (!event.zoneId) return prevBuckets;
// If the item was dropped in an invalid zone, do nothing
if (!event.valid) return prevBuckets;
// If the item was dropped in the zone it was already in, do nothing
if (event.zoneId === event.previousZoneId) return prevBuckets;
// Create a copy of the current buckets
const newBuckets = { ...prevBuckets };
// Remove the item from its previous bucket
const prevKey = event.previousZoneId;
if (prevKey) {
newBuckets[prevKey] = newBuckets[prevKey].filter(
(id) => id !== event.draggableId,
);
}
// Add the item to the target bucket
newBuckets[event.zoneId] = newBuckets[event.zoneId].concat(
event.draggableId,
);
return newBuckets;
});
};
return (
Todo
{buckets["zone-1"].map((itemId) => (
Item {itemId}
))}
In Progress
{buckets["zone-2"].map((itemId) => (
Item {itemId}
))}
Done
{buckets["zone-3"].map((itemId) => (
Item {itemId}
))}
);
}
export default App;
```
#### Dashboard-type arrangements
```tsx lines theme={null}
import { useState } from "react";
import { DndSort, Grid, type DndSortChangeEvent } from "@servicetitan/anvil2";
type Buckets = {
[key: string]: (string | number)[];
};
function App() {
const [_mostRecentEvent, setMostRecentEvent] = useState();
const [buckets, setBuckets] = useState({
"zone-1": ["A"],
"zone-2": ["B"],
"zone-3": ["C"],
"zone-4": ["D"],
});
const someStylesOfYourChoosing = {
flexDirection: "column",
width: "100%",
} as const;
const handleDrop = (event: DndSortChangeEvent) => {
console.info(event);
setMostRecentEvent(event);
setBuckets((prevBuckets) => {
// If the item wasn't dropped in a zone, do nothing
if (!event.zoneId) return prevBuckets;
// If the item was dropped in an invalid zone, do nothing
if (!event.valid) return prevBuckets;
// If the item was dropped in the zone it was already in, do nothing
if (event.zoneId === event.previousZoneId) return prevBuckets;
// Create a copy of the current buckets
const newBuckets = { ...prevBuckets };
const targetBucketItems = newBuckets[event.zoneId];
const draggableId = event.draggableId;
const previousZoneId = event.previousZoneId;
// Check if there's an item in the target zone and it's not the item being dragged
if (
targetBucketItems &&
targetBucketItems.length > 0 &&
targetBucketItems[0] !== draggableId
) {
const itemToSwapOut = targetBucketItems[0]; // Assuming only one item per zone for simplicity or taking the first one
// Remove the item from its previous bucket (the draggableId)
if (previousZoneId) {
newBuckets[previousZoneId] = newBuckets[previousZoneId].filter(
(id) => id !== draggableId,
);
}
// Add the item that was in the target bucket to the previous bucket
if (previousZoneId) {
// Only if there was a previous zone
newBuckets[previousZoneId] =
newBuckets[previousZoneId].concat(itemToSwapOut);
}
// Replace the item in the target bucket with the draggableId
newBuckets[event.zoneId] = [draggableId]; // Assuming only one item per zone
} else {
// --- Original logic if no swap or if target bucket is empty ---
// Remove the item from its previous bucket
if (previousZoneId) {
newBuckets[previousZoneId] = newBuckets[previousZoneId].filter(
(id) => id !== draggableId,
);
}
// Add the item to the target bucket
newBuckets[event.zoneId] = newBuckets[event.zoneId].concat(draggableId);
}
return newBuckets;
});
};
return (
{buckets["zone-1"].map((itemId) => (
Dashboard item {itemId}
))}
{buckets["zone-2"].map((itemId) => (
Dashboard item {itemId}
))}
{buckets["zone-3"].map((itemId) => (
Dashboard item {itemId}
))}
{buckets["zone-4"].map((itemId) => (
Dashboard item {itemId}
))}
);
}
export default App;
```
## How to Use
Use the base configurations of icons, drop zones
```tsx lines theme={null}
import { Dnd } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
```tsx lines theme={null}
function App() {
return (
);
}
export default App;
```
***
