Prioritizing tasks
Let people arrange a short, known collection in the order they want it completed.
Components / Data
A keyboard and pointer accessible list that reports committed item moves.
Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.
Click a task to open it, or drag it to reorder.
bunx --bun @getweini/cli@latest add reorderable-listImport the installed files into your app, keep the ordered array in a parent model, and render a ReorderableItem for each value exposed by the default slot. The default dragMode="item" lets non-interactive row content start a drag while keeping a handle for keyboard access; set dragMode="handle" to opt into handle-only pointer dragging.
<script setup lang="ts">
import { ref } from 'vue'
import ReorderableHandle from './components/ui/reorderable-list/ReorderableHandle.vue'
import ReorderableItem from './components/ui/reorderable-list/ReorderableItem.vue'
import ReorderableList from './components/ui/reorderable-list/ReorderableList.vue'
const tasks = ref([
{ id: 'research', title: 'Review customer feedback' },
{ id: 'outline', title: 'Draft the release outline' },
{ id: 'publish', title: 'Prepare the launch notes' },
])
const messages = {
grab: (label: string) => `Reorder ${label}`,
pickedUp: (label: string, position: number, total: number) =>
`${label} picked up, position ${position} of ${total}`,
moved: (label: string, position: number, total: number) =>
`${label} moved to position ${position} of ${total}`,
dropped: (label: string, position: number, total: number) =>
`${label} dropped at position ${position} of ${total}`,
cancelled: (label: string) => `Reordering ${label} cancelled`,
instructions:
'Press Space or Enter to pick up or drop an item. Use arrow keys to move it, or Escape to cancel.',
}
</script>
<template>
<ReorderableList v-model="tasks" :messages="messages" aria-label="Tasks">
<template #default="{ items }">
<ReorderableItem v-for="task in items" :key="task.id" :value="task.id" :label="task.title">
<span class="min-w-0 flex-1 truncate">{{ task.title }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
</template>In item mode, buttons, links, inputs, and other interactive descendants keep their own behavior. Add data-reorderable-ignore to any other nested control that should not start a row drag. Keyboard focus and drag commands remain on the handle when present. The library suppresses the click produced by a completed pointer drag; add row click behavior yourself and use a separate native button or link for an explicit action.
Let people arrange a short, known collection in the order they want it completed.
Use horizontal orientation when the order reads across a row. Arrow keys follow the orientation and reverse for right-to-left content.
Use orientation="horizontal" when items appear in a horizontal scroller.
<script setup lang="ts">
import { ref } from 'vue'
import ReorderableHandle from './components/ui/reorderable-list/ReorderableHandle.vue'
import ReorderableItem from './components/ui/reorderable-list/ReorderableItem.vue'
import ReorderableList from './components/ui/reorderable-list/ReorderableList.vue'
const stages = ref(['Plan', 'Design', 'Build', 'Ship'])
const messages = {
grab: (label: string) => `Reorder ${label}`,
pickedUp: (label: string, position: number, total: number) =>
`${label} picked up, position ${position} of ${total}`,
moved: (label: string, position: number, total: number) =>
`${label} moved to position ${position} of ${total}`,
dropped: (label: string, position: number, total: number) =>
`${label} dropped at position ${position} of ${total}`,
cancelled: (label: string) => `Reordering ${label} cancelled`,
instructions:
'Press Space or Enter to pick up or drop an item. Use arrow keys to move it, or Escape to cancel.',
}
</script>
<template>
<ReorderableList
v-model="stages"
orientation="horizontal"
:messages="messages"
aria-label="Project stages"
class="max-w-full"
>
<template #default="{ items }">
<ReorderableItem v-for="stage in items" :key="stage" :value="stage" :label="stage">
<span class="whitespace-nowrap">{{ stage }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
</template>Set name to contribute one hidden form value per row, in the committed DOM order.
<script setup lang="ts">
import { ref } from 'vue'
import ReorderableHandle from './components/ui/reorderable-list/ReorderableHandle.vue'
import ReorderableItem from './components/ui/reorderable-list/ReorderableItem.vue'
import ReorderableList from './components/ui/reorderable-list/ReorderableList.vue'
const selected = ref(['alpha', 'beta', 'gamma'])
const messages = {
grab: (label: string) => `Reorder ${label}`,
pickedUp: (label: string, position: number, total: number) =>
`${label} picked up, position ${position} of ${total}`,
moved: (label: string, position: number, total: number) =>
`${label} moved to position ${position} of ${total}`,
dropped: (label: string, position: number, total: number) =>
`${label} dropped at position ${position} of ${total}`,
cancelled: (label: string) => `Reordering ${label} cancelled`,
instructions:
'Press Space or Enter to pick up or drop an item. Use arrow keys to move it, or Escape to cancel.',
}
</script>
<template>
<form class="grid max-w-md gap-3" @submit.prevent>
<ReorderableList v-model="selected" :messages="messages" name="priority" aria-label="Priority">
<template #default="{ items }">
<ReorderableItem v-for="item in items" :key="item" :value="item" :label="item">
<span class="min-w-0 flex-1 capitalize">{{ item }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
<button type="submit" class="w-fit rounded-ui bg-primary px-3 py-2 text-primary-foreground">
Save priority
</button>
</form>
</template>Group related lists with unique list-id values to allow pointer dragging in both axes and keyboard transfers. Each root retains its own controlled array; handle both model updates and the group's move event in the parent. Commit the source and destination arrays together so the item stays unique across the group.
<script setup lang="ts">
import { ref } from 'vue'
import ReorderableHandle from './components/ui/reorderable-list/ReorderableHandle.vue'
import ReorderableItem from './components/ui/reorderable-list/ReorderableItem.vue'
import ReorderableList from './components/ui/reorderable-list/ReorderableList.vue'
import ReorderableListGroup from './components/ui/reorderable-list/ReorderableListGroup.vue'
interface Task {
id: string
title: string
}
const backlog = ref<Task[]>([
{ id: 'research', title: 'Review customer feedback' },
{ id: 'outline', title: 'Draft the release outline' },
])
const inProgress = ref<Task[]>([{ id: 'launch', title: 'Prepare launch notes' }])
const done = ref<Task[]>([])
const messages = {
grab: (label: string) => `Reorder ${label}`,
pickedUp: (label: string, position: number, total: number) =>
`${label} picked up, position ${position} of ${total}`,
moved: (label: string, position: number, total: number) =>
`${label} moved to position ${position} of ${total}`,
dropped: (label: string, position: number, total: number) =>
`${label} dropped at position ${position} of ${total}`,
cancelled: (label: string) => `Reordering ${label} cancelled`,
instructions:
'Press Space or Enter to lift and drop. Use arrows to reorder, or Escape to cancel.',
}
const groupMessages = {
instructions: 'While an item is lifted, press Control and an arrow key to move between lists.',
preview: (label: string, to: string | number, position: number, total: number) =>
`Moving ${label} to ${to}, position ${position} of ${total}`,
transferred: (
label: string,
from: string | number,
to: string | number,
position: number,
total: number,
) => `${label} moved from ${from} to ${to}, position ${position} of ${total}`,
}
</script>
<template>
<ReorderableListGroup
:messages="groupMessages"
class="grid gap-4 sm:grid-cols-3"
aria-label="Project board"
>
<ReorderableList v-model="backlog" list-id="Backlog" :messages="messages" aria-label="Backlog">
<template #default="{ items }">
<ReorderableItem v-for="task in items" :key="task.id" :value="task.id" :label="task.title">
<span class="min-w-0 flex-1 truncate">{{ task.title }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
<ReorderableList
v-model="inProgress"
list-id="In progress"
:messages="messages"
aria-label="In progress"
>
<template #default="{ items }">
<ReorderableItem v-for="task in items" :key="task.id" :value="task.id" :label="task.title">
<span class="min-w-0 flex-1 truncate">{{ task.title }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
<ReorderableList v-model="done" list-id="Done" :messages="messages" aria-label="Done">
<template #default="{ items }">
<ReorderableItem v-for="task in items" :key="task.id" :value="task.id" :label="task.title">
<span class="min-w-0 flex-1 truncate">{{ task.title }}</span>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
</ReorderableListGroup>
</template>Keep the row body draggable while providing a separate native action button. The list handles drag thresholds and prevents the completed drag from triggering the row's click handler; the application owns what a row click or action button does.
<script setup lang="ts">
import { ref } from 'vue'
import Button from './components/ui/button/Button.vue'
import ReorderableHandle from './components/ui/reorderable-list/ReorderableHandle.vue'
import ReorderableItem from './components/ui/reorderable-list/ReorderableItem.vue'
import ReorderableList from './components/ui/reorderable-list/ReorderableList.vue'
const tasks = ref([
{ id: 'research', title: 'Review customer feedback' },
{ id: 'outline', title: 'Draft the release outline' },
{ id: 'publish', title: 'Prepare the launch notes' },
])
const openedTask = ref('')
const messages = {
grab: (label: string) => `Reorder ${label}`,
pickedUp: (label: string, position: number, total: number) =>
`${label} picked up, position ${position} of ${total}`,
moved: (label: string, position: number, total: number) =>
`${label} moved to position ${position} of ${total}`,
dropped: (label: string, position: number, total: number) =>
`${label} dropped at position ${position} of ${total}`,
cancelled: (label: string) => `Reordering ${label} cancelled`,
instructions:
'Press Space or Enter to pick up or drop an item. Use arrow keys to move it, or Escape to cancel.',
}
</script>
<template>
<ReorderableList v-model="tasks" :messages="messages" aria-label="Tasks">
<template #default="{ items }">
<ReorderableItem
v-for="task in items"
:key="task.id"
:value="task.id"
:label="task.title"
@click="openedTask = task.title"
>
<span class="min-w-0 flex-1 truncate">{{ task.title }}</span>
<Button
variant="ghost"
size="sm"
:aria-label="`Open ${task.title}`"
@click.stop="openedTask = task.title"
>
Open
</Button>
<ReorderableHandle />
</ReorderableItem>
</template>
</ReorderableList>
<p role="status" class="text-sm text-muted-foreground">
{{ openedTask ? `Opened: ${openedTask}` : 'Click a task to open it, or drag it to reorder.' }}
</p>
</template>Every public prop, event, slot, and exposed member of the installed Vue parts is listed below. Native attributes also work where the component uses a native element.
| Name | Type or signature | Default | What it does |
|---|---|---|---|
defaultslot | (() => unknown) | undefined | Optional | Content shown inside ReorderableHandle. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
valueprop | ReorderableValue | Required | Stable, unique value identifying this item within its list. |
labelprop | string | undefined | Not set | Optional name used in accessible drag announcements. Defaults to the item's text. |
disabledprop | boolean | undefined | false | Prevent interaction and show the disabled state. |
defaultslot | () => unknown | Required | Content shown inside ReorderableItem. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
modelValuemodel | T[] | Required | The ordered values. Update the array in response to `update:modelValue` to commit a move. |
listIdprop | ReorderableValue | undefined | Not set | Required when this list is a child of ReorderableListGroup. |
orientationprop | ReorderableOrientation | undefined | "vertical" | Arrange items horizontally or vertically. |
dragModeprop | "item" | "handle" | undefined | Not set | Pointer drag surface. `item` enables the non-interactive row surface; `handle` opts into handle-only dragging. |
disabledprop | boolean | undefined | Not set | Prevent interaction and show the disabled state. |
nameprop | string | undefined | Not set | When set, each item contributes one hidden input with the same name. |
messagesprop | ReorderableListMessages | Required | Supply the text this component displays for its built-in actions and states. |
update:modelValueevent | [items: T[]] | — | Requests a new model value from the parent. |
reorderevent | [event: ReorderEvent] | — | Emitted when reorder happens. |
defaultslot | ((props: { items: T[]; }) => unknown) | undefined | Optional | Content shown inside ReorderableList. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
messagesprop | ReorderableListGroupMessages | Required | Supply the text this component displays for its built-in actions and states. |
moveevent | [event: ReorderableListMoveEvent] | — | Emitted when move happens. |
defaultslot | () => unknown | Required | Content shown inside ReorderableListGroup. |
// packages/frameworks/vue/components/reorderable-list/types.ts
import type {
ReorderableListGroupMessages,
ReorderableListMessages,
ReorderableListMoveEvent,
ReorderableOrientation,
ReorderableValue,
ReorderEvent,
} from '@getweini/vue/primitives/reorderable-list'
export type {
ReorderableListGroupMessages,
ReorderableListMessages,
ReorderableListMoveEvent,
ReorderableOrientation,
ReorderableValue,
ReorderEvent,
}
export interface ReorderableListProps<T> {
/** The ordered values. Update the array in response to `update:modelValue` to commit a move. */
modelValue: T[]
/** Required when this list is a child of ReorderableListGroup. */
listId?: ReorderableValue
orientation?: ReorderableOrientation
/** Pointer drag surface. `item` enables the non-interactive row surface; `handle` opts into handle-only dragging. */
dragMode?: 'handle' | 'item'
disabled?: boolean
/** When set, each item contributes one hidden input with the same name. */
name?: string
messages: ReorderableListMessages
}
export interface ReorderableItemProps {
/** Stable, unique value identifying this item within its list. */
value: ReorderableValue
/** Optional name used in accessible drag announcements. Defaults to the item's text. */
label?: string
disabled?: boolean
}
export type ReorderableListReorderEvent = ReorderEvent
export interface ReorderableListGroupProps {
messages: ReorderableListGroupMessages
}
// packages/frameworks/vue/dist/vue/primitives/reorderable-list/index.d.ts
import { type ComponentPublicInstance, type ComputedRef, type InjectionKey, type Ref, type ShallowRef } from 'vue';
export type ReorderableValue = string | number;
export type ReorderableOrientation = 'vertical' | 'horizontal';
/** Application-owned copy for the handle name, instructions, and live announcements. */
export interface ReorderableListMessages {
/** Accessible name of a drag handle, for example `Reorder ${label}`. */
grab: (label: string) => string;
pickedUp: (label: string, position: number, total: number) => string;
moved: (label: string, position: number, total: number) => string;
dropped: (label: string, position: number, total: number) => string;
cancelled: (label: string) => string;
/** Keyboard instructions referenced by every drag target through `aria-describedby`. */
instructions: string;
}
export interface ReorderableListGroupMessages {
/** Keyboard instructions while moving an item between grouped lists. */
instructions: string;
preview: (label: string, toList: ReorderableValue, position: number, total: number) => string;
transferred: (label: string, fromList: ReorderableValue, toList: ReorderableValue, position: number, total: number) => string;
}
/** A committed move, using zero-based indexes in the rendered order. */
export interface ReorderEvent {
value: ReorderableValue;
from: number;
to: number;
}
/** A cross-list move request. Each list emits its own proposed model first. */
export interface ReorderableListMoveEvent {
value: ReorderableValue;
fromList: ReorderableValue;
toList: ReorderableValue;
from: number;
to: number;
}
/** One item's extent along the list axis, in reading-direction space. */
export interface ReorderableSlot {
start: number;
end: number;
}
export interface ReorderableListBehaviorProps<T> {
modelValue: T[];
listId?: ReorderableValue;
orientation?: ReorderableOrientation;
dragMode?: 'handle' | 'item';
disabled?: boolean;
name?: string;
messages: ReorderableListMessages;
}
export interface ReorderableListCallbacks<T> {
onUpdate: (items: T[]) => void;
onReorder: (event: ReorderEvent) => void;
}
export interface ReorderableItemOptions {
value: ReorderableValue;
label?: string;
disabled?: boolean;
}
interface ReorderableItemRecord {
value: () => ReorderableValue;
label: () => string;
refreshLabel: () => void;
disabled: () => boolean;
element: ShallowRef<HTMLElement | null>;
handle: () => HTMLElement | null;
}
interface ReorderableGroupListRecord {
id: ReorderableValue;
element: () => HTMLElement | null;
records: () => ReorderableItemRecord[];
model: () => unknown[];
orientation: () => ReorderableOrientation;
disabled: () => boolean;
update: (items: unknown[]) => void;
focus: (value: ReorderableValue) => boolean;
confirmMove: (value: ReorderableValue) => void;
announceCancelled: (label: string) => void;
}
interface ReorderableGroupTarget {
listId: ReorderableValue;
index: number;
}
export interface ReorderableListGroupContext {
instructionsId: string;
instructions: () => string;
target: Readonly<ShallowRef<ReorderableGroupTarget | null>>;
isTransferring: Readonly<Ref<boolean>>;
registerList: (record: ReorderableGroupListRecord) => () => void;
validateValues: () => void;
start: (listId: ReorderableValue, value: ReorderableValue, label: string, from: number, total: number) => void;
clear: () => void;
pointerTarget: (sourceList: ReorderableValue, pointerX: number, pointerY: number) => ReorderableGroupTarget | null;
keyboardTarget: (sourceList: ReorderableValue, direction: 1 | -1) => ReorderableGroupTarget | 'source' | null;
setTarget: (target: ReorderableGroupTarget | null) => void;
targetCount: (listId: ReorderableValue) => number;
indicatorStyle: (listId: ReorderableValue) => Record<string, string> | null;
transfer: (fromList: ReorderableValue, fromIndex: number, toList: ReorderableValue, toIndex: number, label: string) => ReorderableListMoveEvent | null;
}
type DragMode = 'keyboard' | 'pointer';
export interface ReorderableListContext {
orientation: ComputedRef<ReorderableOrientation>;
surfaceDragMode: ComputedRef<'handle' | 'item'>;
disabled: ComputedRef<boolean>;
name: ComputedRef<string | undefined>;
instructionsId: string;
groupInstructionsId?: string;
group: ReorderableListGroupContext | null;
listId: () => ReorderableValue | undefined;
isGroupTarget: (value: ReorderableValue) => boolean;
groupTargetIndex: () => number | null;
messages: () => ReorderableListMessages;
liftedValue: Readonly<ShallowRef<ReorderableValue | null>>;
overValue: Readonly<ShallowRef<ReorderableValue | null>>;
committedValue: Readonly<ShallowRef<ReorderableValue | null>>;
dragMode: Readonly<Ref<DragMode | null>>;
tabStop: () => ReorderableValue | undefined;
register: (record: ReorderableItemRecord) => void;
unregister: (record: ReorderableItemRecord) => void;
}
export interface ReorderableItemContext {
label: () => string;
messages: () => ReorderableListMessages;
instructionsId: string;
describedBy: ComputedRef<string>;
isDisabled: ComputedRef<boolean>;
isLifted: ComputedRef<boolean>;
isDragging: ComputedRef<boolean>;
isTabStop: ComputedRef<boolean>;
registerHandle: (handle: ShallowRef<HTMLElement | null>) => void;
unregisterHandle: (handle: ShallowRef<HTMLElement | null>) => void;
}
export declare const reorderableListContext: InjectionKey<ReorderableListContext>;
export declare const reorderableItemContext: InjectionKey<ReorderableItemContext>;
export declare const reorderableListGroupContext: InjectionKey<ReorderableListGroupContext>;
export declare function useReorderableListContext(component: string): ReorderableListContext;
export declare function useReorderableItemContext(component: string): ReorderableItemContext;
export declare function useReorderableListGroupContext(component: string): ReorderableListGroupContext;
export declare function useReorderableListGroup(messages: () => ReorderableListGroupMessages, onMove: (event: ReorderableListMoveEvent) => void): {
instructionsId: string;
announcement: Ref<string, string>;
context: ReorderableListGroupContext;
};
/** Return a new array with one entry moved; the input is never mutated. */
export declare function moveArrayItem<T>(list: readonly T[], from: number, to: number): T[];
/**
* Axis offsets that preview moving `from` to `to` without changing DOM order.
* Neighbours move by the dragged item's size plus its adjacent gap; the dragged
* item moves to the edge of the target slot, so mixed item sizes stay aligned.
*/
export declare function calculateReorderOffsets(slots: readonly ReorderableSlot[], from: number, to: number): number[];
/** The slot whose midpoint the dragged item's midpoint has crossed. */
export declare function findReorderTarget(slots: readonly ReorderableSlot[], from: number, delta: number): number;
/**
* Own the committed order, drag session, pointer and keyboard paths, FLIP
* motion, autoscroll, roving focus, and live announcements of one list.
*/
export declare function useReorderableList<T>(props: ReorderableListBehaviorProps<T>, callbacks: ReorderableListCallbacks<T>): {
items: ComputedRef<T[]>;
orientation: ComputedRef<ReorderableOrientation>;
surfaceDragMode: ComputedRef<"item" | "handle">;
disabled: ComputedRef<boolean>;
isActive: ComputedRef<boolean>;
isDragging: ComputedRef<boolean>;
announcement: Ref<string, string>;
instructionsId: string;
indicatorStyle: ShallowRef<Record<string, string> | null, Record<string, string> | null>;
groupIndicatorStyle: ComputedRef<Record<string, string> | null>;
bindList: (element: Element | ComponentPublicInstance | null) => void;
drop: () => Promise<void>;
cancel: () => Promise<void>;
handlePointerdown: (event: PointerEvent) => void;
handlePointermove: (event: PointerEvent) => void;
handlePointerup: (event: PointerEvent) => void;
handlePointercancel: (event: PointerEvent) => void;
handleContextmenu: (event: Event) => void;
handleKeydown: (event: KeyboardEvent) => void;
handleFocusin: (event: FocusEvent) => void;
handleFocusout: (event: FocusEvent) => void;
};
/** Register one list item, its optional handle, roving tab stop, and form value. */
export declare function useReorderableItem(options: ReorderableItemOptions): {
element: ShallowRef<HTMLElement | null, HTMLElement | null>;
isDisabled: ComputedRef<boolean>;
isLifted: ComputedRef<boolean>;
isDragging: ComputedRef<boolean>;
isOver: ComputedRef<boolean>;
isCommitted: ComputedRef<boolean>;
isRowDragTarget: ComputedRef<boolean>;
hasHandle: ComputedRef<boolean>;
tabIndex: ComputedRef<0 | -1 | undefined>;
describedBy: ComputedRef<string | undefined>;
hiddenInput: ComputedRef<{
name: string;
value: string;
disabled: boolean;
} | undefined>;
};
/** A native button that becomes the item's only pointer and keyboard drag target. */
export declare function useReorderableHandle(): {
element: ShallowRef<HTMLElement | null, HTMLElement | null>;
ariaLabel: ComputedRef<string>;
describedBy: ComputedRef<string>;
tabIndex: ComputedRef<0 | -1>;
isDisabled: ComputedRef<boolean>;
isLifted: ComputedRef<boolean>;
isDragging: ComputedRef<boolean>;
};
export {};modelValue is required. Reordering emits a new array; the parent commits it to update the visible order.ReorderableListGroup requires localized instructions, preview, and transferred messages. Grouped lists require unique list-id values and globally unique item values. Cross-list moves emit proposed arrays from both lists before the group's move event; the parent must commit both arrays together.{ items }. Render one ReorderableItem for each model entry, in model order, and use a stable key.ReorderableList uses a native ul, and each ReorderableItem uses a native li. The handle is a native button.name adds one hidden input for every item value. Omit it when form submission should not include the list.messages object.