Sortable

Basic building blocks for sortable interfaces.

#
Documentation

#
Usage

Item A

Item B

Item C


"use client";
 
import { Box } from "@optiaxiom/react";
import { Sortable } from "@optiaxiom/react/unstable";
import { useState } from "react";
 
export function App() {
  const [items, setItems] = useState(["A", "B", "C"]);
 
  return (
    <Sortable
      alignItems="center"
      fontFamily="mono"
      fontSize="md"
      fontWeight="600"
      items={items}
      onItemsChange={setItems}
    >
      {(item) => (
        <Box
          bg="bg.avatar.neutral"
          p="12"
          rounded="sm"
          textAlign="center"
          w="224"
        >
          Item {item}
        </Box>
      )}
    </Sortable>
  );
}

#
Anatomy


import {
  Sortable,
  SortableHandle,
  SortableItem,
} from "@optiaxiom/react/unstable";
 
export default () => (
  <Sortable>
    <SortableItem>
      <SortableHandle />
    </SortableItem>
  </Sortable>
);

#
Basic

Sortable works with a list of items provided via the items prop. Each item must be a unique string identifying the sortable item within the list.

Next we provide a render prop in children that takes in two arguments - the item and the index - to render the contents of each item.

Finally we use SortableItem to render each sortable element inside the render function.

0. Item A

1. Item B

2. Item C


"use client";
 
import { Sortable, SortableItem } from "@optiaxiom/react/unstable";
 
export function App() {
  return (
    <Sortable items={["A", "B", "C"]}>
      {(item, index) => (
        <SortableItem border="1">
          {index}. Item {item}
        </SortableItem>
      )}
    </Sortable>
  );
}

#
Sorting

Notice in the previous demo items are draggable but they always revert back to their original position.

We need to use either the onItemsChange or onChange prop to store the new sorted state.

Only use either onItemsChange or onChange. Do not use both props on the same component.

Using onValueChange is the simplest way to handle sorting for smaller pieces of data where we can update the sorting rank for all items in one call.

Item A

Item B

Item C


"use client";
 
import { Sortable, SortableItem } from "@optiaxiom/react/unstable";
import { useState } from "react";
 
export function App() {
  const [items, setItems] = useState(["A", "B", "C"]);
 
  return (
    <Sortable items={items} onItemsChange={setItems}>
      {(item) => <SortableItem border="1">Item {item}</SortableItem>}
    </Sortable>
  );
}

Using onChange is necessary in cases where we’re sorting a large number of items and we only want to mutate the item that is being dragged.

Item A

Item B

Item C

App.tsx


"use client";
 
import { Sortable, SortableItem } from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { calculateRank } from "./calculateRank";
 
export function App() {
  const [data, setData] = useState([
    {
      id: "A",
      rank: 10_000,
    },
    {
      id: "B",
      rank: 20_000,
    },
    {
      id: "C",
      rank: 30_000,
    },
  ]);
 
  return (
    <Sortable
      items={data.toSorted((a, b) => a.rank - b.rank).map((item) => item.id)}
      onChange={({ items, source }) => {
        setData(
          data.map((item) =>
            item.id === source
              ? {
                  ...item,
                  rank: calculateRank(data, source, items),
                }
              : item,
          ),
        );
      }}
    >
      {(item) => <SortableItem border="1">Item {item}</SortableItem>}
    </Sortable>
  );
}

#
Drag handle

By default the whole item acts as the drag handle, but we can use the SortableHandle component to render separate drag handles within the items.

Item A

Item B

Item C


"use client";
 
import {
  Sortable,
  SortableHandle,
  SortableItem,
} from "@optiaxiom/react/unstable";
import { IconGripVertical } from "@tabler/icons-react";
import { useState } from "react";
 
export function App() {
  const [items, setItems] = useState(["A", "B", "C"]);
 
  return (
    <Sortable items={items} onItemsChange={setItems}>
      {(item) => (
        <SortableItem alignItems="center" border="1" display="flex">
          <SortableHandle>
            <IconGripVertical size={20} />
          </SortableHandle>
          Item {item}
        </SortableItem>
      )}
    </Sortable>
  );
}

App.tsx


"use client";
 
import { Button, EllipsisMenuButton, Flex, Text } from "@optiaxiom/react";
import {
  Card,
  CardHeader,
  CardLink,
  Menu,
  MenuContent,
  MenuTrigger,
  Sortable,
  SortableHandle,
  SortableItem,
} from "@optiaxiom/react/unstable";
import { IconGripVertical } from "@tabler/icons-react";
import { useState } from "react";
 
import { data } from "./data";
 
export function App() {
  const [items, setItems] = useState(() => Object.keys(data));
 
  return (
    <Sortable items={items} onItemsChange={setItems}>
      {(item, index) => (
        <Flex flexDirection="row">
          <Text color="fg.secondary" fontSize="md" w="20">
            {index + 1}
          </Text>
          <SortableItem asChild>
            <Card flex="1">
              <CardHeader
                addonAfter={
                  <Menu options={[{ label: "Edit" }]}>
                    <MenuTrigger asChild>
                      <EllipsisMenuButton
                        appearance="subtle"
                        aria-label="actions"
                        ml="auto"
                      />
                    </MenuTrigger>
                    <MenuContent />
                  </Menu>
                }
                addonBefore={
                  <SortableHandle
                    asChild
                    color="fg.tertiary"
                    transition="colors"
                  >
                    <Button appearance="subtle" icon={<IconGripVertical />} />
                  </SortableHandle>
                }
                description={data[item].description}
              >
                <CardLink href="data:,">{data[item].title}</CardLink>
              </CardHeader>
            </Card>
          </SortableItem>
        </Flex>
      )}
    </Sortable>
  );
}

#
Props

#
Sortable

Supports all Box props in addition to its own. Renders a <div> element.

Prop
`asChild` Change the default rendered element for the one passed as a child, merging their props and behavior. Read the Composition guide for more details. `false \| true`
`className` `string`
`items*` An array of item IDs in controlled mode. `string[]`
`onChange` Event handler that is called when items are re-sorted with full information about the event. `(data: { items: string[]; source: string; }) => void`
`onItemsChange` Handler that is called when the item IDs are re-sorted. `(value: string[]) => void`

#
SortableItem

Supports all Box props in addition to its own. Renders a <div> element.

Prop
`asChild` Change the default rendered element for the one passed as a child, merging their props and behavior. Read the Composition guide for more details. `false \| true`
`className` `string`

#
SortableHandle

Supports all Box props in addition to its own. Renders a <div> element.

Prop
`asChild` Change the default rendered element for the one passed as a child, merging their props and behavior. Read the Composition guide for more details. `false \| true`
`className` `string`

#
Changelog

#
1.5.0

Added component

Sortable

#
Documentation

#
Usage

#
Anatomy

#
Basic

#
Sorting

App.tsx

calculateRank.ts

#
Drag handle

#
Card example

Launch Scooter Beta Sign Up

Age Experiment

Multi-Armed Bandit for Images

App.tsx

data.ts

#
Props

#
Sortable

#
SortableItem

#
SortableHandle

#
Changelog

#
1.5.0