configure
The global settings, the screen reader strings and alertToScreenReader.
The settings on this page are global: they apply to every zone in every document. The keyboard and screen readers guide shows them in use.
configure
Sets the global settings of the library. Keys that are left out (or undefined) are not touched. It only sets module state and touches no DOM, so it is safe to call during SSR. Every key keeps the validation and the side effects of the setting it applies: - idKey throws when a zone is mounted or the value is not a string - keyboardDragTrigger: null restores "space_or_enter"; it updates the screen-reader instructions - ariaStrings: null restores the English strings; existing instruction elements update immediately - debug turns console.debug output on or off, and has to be a boolean
function configure(config: DndConfig): void DndConfig
The global settings, see configure.
interface DndConfig | Name | Type | Default | Description |
|---|---|---|---|
idKey? | string | "id" | The key of each item's id. Throws if any zone is mounted. |
keyboardDragTrigger? | "space" | "enter" | "space_or_enter" | null | "space_or_enter" | The keys that start and stop a keyboard drag. null restores the default. |
ariaStrings? | AriaStrings | null | - | A full locale that replaces the English screen reader strings: keys left out use English. null restores English. |
debug? | boolean | false | Turns console.debug output on or off. |
AriaStrings
The strings the library speaks to screen readers, set with configure({ ariaStrings }).
Every message key receives the same core context - itemLabel, zoneLabel, position, count -
so a consumer can word any of them positionally. Only dragStarted carries an extra.
The labels are the aria-label attributes of the item and the zone, or empty.
interface AriaStrings | Name | Type | Default | Description |
|---|---|---|---|
dragStarted? | (ctx: {
itemLabel: string;
zoneLabel: string;
position: number;
count: number;
canMoveBetweenZones: boolean;
}) => string | - | Announced when a keyboard drag starts. canMoveBetweenZones is true when another zone can take the item.
The English default tells the user to use the arrow keys, and to tab to another list when it can. |
movedToPosition? | (ctx: {
itemLabel: string;
zoneLabel: string;
position: number;
count: number;
}) => string | - | Announced when an arrow key moves the item within its zone. position counts from 1. |
movedToZoneEnd? | (ctx: {
itemLabel: string;
zoneLabel: string;
position: number;
count: number;
}) => string | - | Announced when the item moves into a zone above or to the left of its zone, which puts it at the end. |
movedToZoneStart? | (ctx: {
itemLabel: string;
zoneLabel: string;
position: number;
count: number;
}) => string | - | Announced when the item moves into a zone below or to the right of its zone, which puts it at the start. |
dropped? | (ctx: {
itemLabel: string;
zoneLabel: string;
position: number;
count: number;
}) => string | - | Announced when a keyboard drag ends, with the zone and the position the item ended in. |
zoneActiveInstruction? | string | ((ctx: {
keyboardDragTrigger: "space" | "enter" | "space_or_enter";
}) => string) | - | The instruction that describes a zone that can be dragged from, linked with aria-describedby. A function
receives the active keyboard drag trigger, so a translation can name the right key. |
zoneDragDisabledInstruction? | string | - | The instruction that describes a zone with dragDisabled, linked with aria-describedby. |
alertToScreenReader
Will make the screen reader alert the provided text to the user, through the same live region the library's own announcements use.
function alertToScreenReader(txt: string, doc?: Document): void