Merge pull request #5277 from xyflow/a11y

feat(a11y): add static support for a11y message localization

.changeset/friendly-monkeys-fry.md

@@ -2,4 +2,4 @@
 '@xyflow/svelte': patch
 ---
 
-Fix data in EdgeProps not typed correctly
+Fix data in `EdgeProps` that was not typed correctly

.changeset/grumpy-spiders-play.md

@@ -1,7 +1,7 @@
 ---
 '@xyflow/react': minor
 '@xyflow/svelte': minor
-'@xyflow/system': minor
+'@xyflow/system': patch
 ---
 
 Improve typing for Nodes

.changeset/late-taxis-press.md

@@ -1,7 +1,7 @@
 ---
 '@xyflow/react': minor
 '@xyflow/svelte': minor
-'@xyflow/system': minor
+'@xyflow/system': patch
 ---
 
 Add an `ease` and `interpolate` option to all function that alter the viewport

.changeset/quiet-forks-visit.md

@@ -0,0 +1,8 @@
+---
+"@xyflow/react": minor
+"@xyflow/svelte": minor
+"@xyflow/system": patch
+---
+
+Add `ariaLabelConfig` prop for customizing UI text like aria labels and descriptions.
+

examples/react/src/App/routes.ts

@@ -1,3 +1,4 @@
+import A11y from '../examples/A11y';
 import Basic from '../examples/Basic';
 import Backgrounds from '../examples/Backgrounds';
 import BrokenNodes from '../examples/BrokenNodes';
@@ -68,6 +69,11 @@ const routes: IRoute[] = [
     path: 'add-node-edge-drop',
     component: AddNodeOnEdgeDrop,
   },
+  {
+    name: 'A11y',
+    path: 'a11y',
+    component: A11y,
+  },
   {
     name: 'Basic',
     path: 'basic',

examples/react/src/examples/A11y/index.tsx

@@ -0,0 +1,94 @@
+import { MouseEvent } from 'react';
+import {
+  ReactFlow,
+  MiniMap,
+  Background,
+  BackgroundVariant,
+  Controls,
+  ReactFlowProvider,
+  Node,
+  Edge,
+  OnNodeDrag,
+  AriaLabelConfig,
+} from '@xyflow/react';
+
+const onNodeDrag: OnNodeDrag = (_, node: Node, nodes: Node[]) => console.log('drag', node, nodes);
+const onNodeDragStart = (_: MouseEvent, node: Node, nodes: Node[]) => console.log('drag start', node, nodes);
+const onNodeDragStop = (_: MouseEvent, node: Node, nodes: Node[]) => console.log('drag stop', node, nodes);
+const onNodeClick = (_: MouseEvent, node: Node) => console.log('click', node);
+
+const initialNodes: Node[] = [
+  {
+    id: '1',
+    type: 'input',
+    data: { label: 'A11y Node 1' },
+    position: { x: 250, y: 5 },
+    className: 'light',
+  },
+  {
+    id: '2',
+    data: { label: 'Node 2' },
+    position: { x: 100, y: 100 },
+    className: 'light',
+  },
+  {
+    id: '3',
+    data: { label: 'Node 3' },
+    position: { x: 400, y: 100 },
+    className: 'light',
+  },
+];
+
+const initialEdges: Edge[] = [
+  { id: 'e1-2', source: '1', target: '2', animated: true },
+  { id: 'e1-3', source: '1', target: '3' },
+];
+
+const ariaLabelConfig: Partial<AriaLabelConfig> = {
+  'node.a11yDescription.default': 'Custom Node Desc.',
+  'node.a11yDescription.keyboardDisabled': 'Custom Keyboard Desc.',
+  'node.a11yDescription.ariaLiveMessage': ({ direction, x, y }) =>
+    `Custom Moved selected node ${direction}. New position, x: ${x}, y: ${y}`,
+  'edge.a11yDescription.default': 'Custom Edge Desc.',
+  'controls.ariaLabel': 'Custom Controls Aria Label',
+  'controls.zoomIn.ariaLabel': 'Custom Zoom in',
+  'controls.zoomOut.ariaLabel': 'Custom Zoom Out',
+  'controls.fitView.ariaLabel': 'Custom Fit View',
+  'controls.interactive.ariaLabel': 'Custom Toggle Interactivity',
+  'minimap.ariaLabel': 'Custom Aria Label',
+};
+
+const A11y = () => {
+  return (
+    <ReactFlow
+      defaultNodes={initialNodes}
+      defaultEdges={initialEdges}
+      onNodesChange={console.log}
+      onNodeClick={onNodeClick}
+      onNodeDragStop={onNodeDragStop}
+      onNodeDragStart={onNodeDragStart}
+      onNodeDrag={onNodeDrag}
+      className="react-flow-basic-example"
+      minZoom={0.2}
+      maxZoom={4}
+      fitView
+      selectNodesOnDrag={false}
+      elevateEdgesOnSelect
+      elevateNodesOnSelect={false}
+      nodeDragThreshold={0}
+      ariaLabelConfig={ariaLabelConfig}
+    >
+      <Background variant={BackgroundVariant.Dots} />
+      <MiniMap />
+      <Controls />
+    </ReactFlow>
+  );
+};
+
+export default function App() {
+  return (
+    <ReactFlowProvider>
+      <A11y />
+    </ReactFlowProvider>
+  );
+}

examples/svelte/src/components/Header/Header.svelte

@@ -3,6 +3,7 @@
 	import { page } from '$app/stores';
 
 	const routes = [
+		'a11y',
 		'add-node-on-drop',
 		'color-mode',
 		'custom-connection-line',

examples/svelte/src/routes/examples/a11y/+page.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import { SvelteFlow, Controls, Background, MiniMap } from '@xyflow/svelte';
+
+	import '@xyflow/svelte/dist/style.css';
+
+	let nodes = $state.raw([
+		{
+			id: 'A',
+			position: { x: 0, y: 0 },
+			data: { label: 'A' }
+		},
+		{ id: 'B', position: { x: -100, y: 150 }, data: { label: 'B' } },
+		{ id: 'C', position: { x: 100, y: 150 }, data: { label: 'C' } },
+		{ id: 'D', position: { x: 0, y: 260 }, data: { label: 'D' } }
+	]);
+
+	let edges = $state.raw([
+		{ id: 'A-B', source: 'A', target: 'B' },
+		{ id: 'A-C', source: 'A', target: 'C' },
+		{ id: 'A-D', source: 'A', target: 'D' }
+	]);
+</script>
+
+<SvelteFlow
+	bind:nodes
+	bind:edges
+	fitView
+	ariaLabelConfig={{
+		'node.a11yDescription.default': 'Svelte Custom Node Desc.',
+		'node.a11yDescription.keyboardDisabled': 'Svelte Custom Keyboard Desc.',
+		'node.a11yDescription.ariaLiveMessage': ({ direction, x, y }) =>
+			`Custom Moved selected node ${direction}. New position, x: ${x}, y: ${y}`,
+		'edge.a11yDescription.default': 'Svelte Custom Edge Desc.',
+		'controls.ariaLabel': 'Svelte Custom Control Aria Label',
+		'controls.zoomIn.ariaLabel': 'Svelte Custom Zoom in',
+		'controls.zoomOut.ariaLabel': 'Svelte Custom Zoom Out',
+		// 'controls.fitView.ariaLabel': 'Svelte Custom Fit View',
+		'controls.interactive.ariaLabel': 'Svelte Custom Toggle Interactivity',
+		'minimap.ariaLabel': 'Svelte Custom Minimap'
+	}}
+>
+	<Controls />
+	<Background />
+	<MiniMap />
+</SvelteFlow>

packages/react/src/additional-components/Controls/Controls.tsx

@@ -19,6 +19,7 @@ const selector = (s: ReactFlowState) => ({
   isInteractive: s.nodesDraggable || s.nodesConnectable || s.elementsSelectable,
   minZoomReached: s.transform[2] <= s.minZoom,
   maxZoomReached: s.transform[2] >= s.maxZoom,
+  ariaLabelConfig: s.ariaLabelConfig,
 });
 
 function ControlsComponent({
@@ -35,10 +36,10 @@ function ControlsComponent({
   children,
   position = 'bottom-left',
   orientation = 'vertical',
-  'aria-label': ariaLabel = 'React Flow controls',
+  'aria-label': ariaLabel,
 }: ControlProps) {
   const store = useStoreApi();
-  const { isInteractive, minZoomReached, maxZoomReached } = useStore(selector, shallow);
+  const { isInteractive, minZoomReached, maxZoomReached, ariaLabelConfig } = useStore(selector, shallow);
   const { zoomIn, zoomOut, fitView } = useReactFlow();
 
   const onZoomInHandler = () => {
@@ -67,22 +68,21 @@ function ControlsComponent({
   };
 
   const orientationClass = orientation === 'horizontal' ? 'horizontal' : 'vertical';
-
   return (
     <Panel
       className={cc(['react-flow__controls', orientationClass, className])}
       position={position}
       style={style}
       data-testid="rf__controls"
-      aria-label={ariaLabel}
+      aria-label={ariaLabel ?? ariaLabelConfig['controls.ariaLabel']}
     >
       {showZoom && (
         <>
           <ControlButton
             onClick={onZoomInHandler}
             className="react-flow__controls-zoomin"
-            title="zoom in"
+            title={ariaLabelConfig['controls.zoomIn.ariaLabel']}
-            aria-label="zoom in"
+            aria-label={ariaLabelConfig['controls.zoomIn.ariaLabel']}
             disabled={maxZoomReached}
           >
             <PlusIcon />
@@ -90,8 +90,8 @@ function ControlsComponent({
           <ControlButton
             onClick={onZoomOutHandler}
             className="react-flow__controls-zoomout"
-            title="zoom out"
+            title={ariaLabelConfig['controls.zoomOut.ariaLabel']}
-            aria-label="zoom out"
+            aria-label={ariaLabelConfig['controls.zoomOut.ariaLabel']}
             disabled={minZoomReached}
           >
             <MinusIcon />
@@ -102,8 +102,8 @@ function ControlsComponent({
         <ControlButton
           className="react-flow__controls-fitview"
           onClick={onFitViewHandler}
-          title="fit view"
+          title={ariaLabelConfig['controls.fitView.ariaLabel']}
-          aria-label="fit view"
+          aria-label={ariaLabelConfig['controls.fitView.ariaLabel']}
         >
           <FitViewIcon />
         </ControlButton>
@@ -112,8 +112,8 @@ function ControlsComponent({
         <ControlButton
           className="react-flow__controls-interactive"
           onClick={onToggleInteractivity}
-          title="toggle interactivity"
+          title={ariaLabelConfig['controls.interactive.ariaLabel']}
-          aria-label="toggle interactivity"
+          aria-label={ariaLabelConfig['controls.interactive.ariaLabel']}
         >
           {isInteractive ? <UnlockIcon /> : <LockIcon />}
         </ControlButton>

packages/react/src/additional-components/MiniMap/MiniMap.tsx

@@ -36,11 +36,11 @@ const selector = (s: ReactFlowState) => {
     translateExtent: s.translateExtent,
     flowWidth: s.width,
     flowHeight: s.height,
+    ariaLabelConfig: s.ariaLabelConfig,
   };
 };
 
 const ARIA_LABEL_KEY = 'react-flow__minimap-desc';
-
 function MiniMapComponent<NodeType extends Node = Node>({
   style,
   className,
@@ -63,14 +63,17 @@ function MiniMapComponent<NodeType extends Node = Node>({
   onNodeClick,
   pannable = false,
   zoomable = false,
-  ariaLabel = 'React Flow mini map',
+  ariaLabel,
   inversePan,
   zoomStep = 10,
   offsetScale = 5,
 }: MiniMapProps<NodeType>) {
   const store = useStoreApi<NodeType>();
   const svg = useRef<SVGSVGElement>(null);
-  const { boundingRect, viewBB, rfId, panZoom, translateExtent, flowWidth, flowHeight } = useStore(selector, shallow);
+  const { boundingRect, viewBB, rfId, panZoom, translateExtent, flowWidth, flowHeight, ariaLabelConfig } = useStore(
+    selector,
+    shallow
+  );
   const elementWidth = (style?.width as number) ?? defaultWidth;
   const elementHeight = (style?.height as number) ?? defaultHeight;
   const scaledWidth = boundingRect.width / elementWidth;
@@ -130,6 +133,8 @@ function MiniMapComponent<NodeType extends Node = Node>({
       }, [])
     : undefined;
 
+  const _ariaLabel = ariaLabel ?? ariaLabelConfig['minimap.ariaLabel'];
+
   return (
     <Panel
       position={position}
@@ -159,7 +164,8 @@ function MiniMapComponent<NodeType extends Node = Node>({
         ref={svg}
         onClick={onSvgClick}
       >
-        {ariaLabel && <title id={labelledBy}>{ariaLabel}</title>}
+        {_ariaLabel && <title id={labelledBy}>{_ariaLabel}</title>}
+
         <MiniMapNodes<NodeType>
           onClick={onSvgNodeClick}
           nodeColor={nodeColor}

packages/react/src/additional-components/MiniMap/types.ts

@@ -83,7 +83,7 @@ export type MiniMapProps<NodeType extends Node = Node> = Omit<HTMLAttributes<SVG
    * There is no text inside the minimap for a screen reader to use as an accessible name, so it's
    * important we provide one to make the minimap accessible. The default is sufficient, but you may
    * want to replace it with something more relevant to your app or product.
-   * @default "React Flow mini map"
+   * @default "Mini Map"
    */
   ariaLabel?: string | null;
   /** Invert direction when panning the minimap viewport. */

packages/react/src/components/A11yDescriptions/index.tsx

@@ -20,10 +20,11 @@ export const ARIA_NODE_DESC_KEY = 'react-flow__node-desc';
 export const ARIA_EDGE_DESC_KEY = 'react-flow__edge-desc';
 export const ARIA_LIVE_MESSAGE = 'react-flow__aria-live';
 
-const selector = (s: ReactFlowState) => s.ariaLiveMessage;
+const ariaLiveSelector = (s: ReactFlowState) => s.ariaLiveMessage;
+const ariaLabelConfigSelector = (s: ReactFlowState) => s.ariaLabelConfig;
 
 function AriaLiveMessage({ rfId }: { rfId: string }) {
-  const ariaLiveMessage = useStore(selector);
+  const ariaLiveMessage = useStore(ariaLiveSelector);
 
   return (
     <div id={`${ARIA_LIVE_MESSAGE}-${rfId}`} aria-live="assertive" aria-atomic="true" style={ariaLiveStyle}>
@@ -33,15 +34,17 @@ function AriaLiveMessage({ rfId }: { rfId: string }) {
 }
 
 export function A11yDescriptions({ rfId, disableKeyboardA11y }: { rfId: string; disableKeyboardA11y: boolean }) {
+  const ariaLabelConfig = useStore(ariaLabelConfigSelector);
+
   return (
     <>
       <div id={`${ARIA_NODE_DESC_KEY}-${rfId}`} style={style}>
-        Press enter or space to select a node.
+        {disableKeyboardA11y
-        {!disableKeyboardA11y && 'You can then use the arrow keys to move the node around.'} Press delete to remove it
+          ? ariaLabelConfig['node.a11yDescription.default']
-        and escape to cancel.{' '}
+          : ariaLabelConfig['node.a11yDescription.keyboardDisabled']}
       </div>
       <div id={`${ARIA_EDGE_DESC_KEY}-${rfId}`} style={style}>
-        Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.
+        {ariaLabelConfig['edge.a11yDescription.default']}
       </div>
       {!disableKeyboardA11y && <AriaLiveMessage rfId={rfId} />}
     </>

packages/react/src/components/NodeWrapper/index.tsx

@@ -142,10 +142,14 @@ export function NodeWrapper<NodeType extends Node>({
       // prevent default scrolling behavior on arrow key press when node is moved
       event.preventDefault();
 
+      const { ariaLabelConfig } = store.getState();
+
       store.setState({
-        ariaLiveMessage: `Moved selected node ${event.key
+        ariaLiveMessage: ariaLabelConfig['node.a11yDescription.ariaLiveMessage']({
-          .replace('Arrow', '')
+          direction: event.key.replace('Arrow', '').toLowerCase(),
-          .toLowerCase()}. New position, x: ${~~internals.positionAbsolute.x}, y: ${~~internals.positionAbsolute.y}`,
+          x: ~~internals.positionAbsolute.x,
+          y: ~~internals.positionAbsolute.y,
+        }),
       });
 
       moveSelectedNodes({

packages/react/src/components/StoreUpdater/index.tsx

@@ -5,7 +5,7 @@
  */
 import { useEffect, useRef } from 'react';
 import { shallow } from 'zustand/shallow';
-import { infiniteExtent, type CoordinateExtent } from '@xyflow/system';
+import { infiniteExtent, type CoordinateExtent, mergeAriaLabelConfig, AriaLabelConfig } from '@xyflow/system';
 
 import { useStore, useStoreApi } from '../../hooks/useStore';
 import type { Node, Edge, ReactFlowState, ReactFlowProps, FitViewOptions } from '../../types';
@@ -68,6 +68,7 @@ const reactFlowFieldsToTrack = [
   'debug',
   'autoPanSpeed',
   'paneClickDistance',
+  'ariaLabelConfig',
 ] as const;
 
 type ReactFlowFieldsToTrack = (typeof reactFlowFieldsToTrack)[number];
@@ -156,6 +157,10 @@ export function StoreUpdater<NodeType extends Node = Node, EdgeType extends Edge
         // Renamed fields
         else if (fieldName === 'fitView') store.setState({ fitViewQueued: fieldValue as boolean });
         else if (fieldName === 'fitViewOptions') store.setState({ fitViewOptions: fieldValue as FitViewOptions });
+
+        if (fieldName === 'ariaLabelConfig') {
+          store.setState({ ariaLabelConfig: mergeAriaLabelConfig(fieldValue as AriaLabelConfig) });
+        }
         // General case
         else store.setState({ [fieldName]: fieldValue });
       }

packages/react/src/container/ReactFlow/index.tsx

@@ -145,6 +145,7 @@ function ReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
     colorMode = 'light',
     debug,
     onScroll,
+    ariaLabelConfig,
     ...rest
   }: ReactFlowProps<NodeType, EdgeType>,
   ref: ForwardedRef<HTMLDivElement>
@@ -306,6 +307,7 @@ function ReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
           onBeforeDelete={onBeforeDelete}
           paneClickDistance={paneClickDistance}
           debug={debug}
+          ariaLabelConfig={ariaLabelConfig}
         />
         <SelectionListener<NodeType, EdgeType> onSelectionChange={onSelectionChange} />
         {children}

packages/react/src/index.ts

@@ -108,6 +108,7 @@ export {
   type NoConnection,
   type NodeConnection,
   type OnReconnect,
+  type AriaLabelConfig,
 } from '@xyflow/system';
 
 // we need this workaround to prevent a duplicate identifier error

packages/react/src/store/initialState.ts

@@ -10,6 +10,7 @@ import {
   NodeOrigin,
   initialConnection,
   CoordinateExtent,
+  defaultAriaLabelConfig,
 } from '@xyflow/system';
 
 import type { Edge, FitViewOptions, InternalNode, Node, ReactFlowStore } from '../types';
@@ -141,6 +142,7 @@ const getInitialState = ({
 
     lib: 'react',
     debug: false,
+    ariaLabelConfig: defaultAriaLabelConfig,
   };
 };
 

packages/react/src/types/component-props.ts

@@ -21,6 +21,7 @@ import type {
   ColorMode,
   SnapGrid,
   OnReconnect,
+  AriaLabelConfig,
 } from '@xyflow/system';
 
 import type {
@@ -666,4 +667,9 @@ export interface ReactFlowProps<NodeType extends Node = Node, EdgeType extends E
    * @default false
    */
   debug?: boolean;
+  /**
+   * Configuration for customizable labels, descriptions, and UI text. Provided keys will override the corresponding defaults.
+   * Allows localization, customization of ARIA descriptions, control labels, minimap labels, and other UI strings.
+   */
+  ariaLabelConfig?: Partial<AriaLabelConfig>;
 }

packages/react/src/types/store.ts

@@ -28,6 +28,7 @@ import {
   type NodeChange,
   type EdgeChange,
   type ParentLookup,
+  type AriaLabelConfig,
 } from '@xyflow/system';
 
 import type {
@@ -67,7 +68,6 @@ export type ReactFlowStore<NodeType extends Node = Node, EdgeType extends Edge =
   domNode: HTMLDivElement | null;
   paneDragging: boolean;
   noPanClassName: string;
-
   panZoom: PanZoomInstance | null;
   minZoom: number;
   maxZoom: number;
@@ -148,6 +148,7 @@ export type ReactFlowStore<NodeType extends Node = Node, EdgeType extends Edge =
 
   lib: string;
   debug: boolean;
+  ariaLabelConfig: AriaLabelConfig;
 };
 
 export type ReactFlowActions<NodeType extends Node, EdgeType extends Edge> = {

packages/svelte/src/lib/components/A11yDescriptions/A11yDescriptions.svelte

@@ -7,15 +7,12 @@
 </script>
 
 <div id={`${ARIA_NODE_DESC_KEY}-${store.flowId}`} class="a11y-hidden">
-  Press enter or space to select a node.
+  {store.disableKeyboardA11y
-  {#if !store.disableKeyboardA11y}
+    ? store.ariaLabelConfig['node.a11yDescription.default']
-    You can then use the arrow keys to move the node around.
+    : store.ariaLabelConfig['node.a11yDescription.keyboardDisabled']}
-  {/if}
-  Press delete to remove it and escape to cancel.
 </div>
 <div id={`${ARIA_EDGE_DESC_KEY}-${store.flowId}`} class="a11y-hidden">
-  Press enter or space to select an edge. You can then press delete to remove it or escape to
+  {store.ariaLabelConfig['edge.a11yDescription.default']}
-  cancel.
 </div>
 
 {#if !store.disableKeyboardA11y}

packages/svelte/src/lib/components/Handle/Handle.svelte

@@ -44,6 +44,8 @@
   );
 
   let store = useStore();
+  let ariaLabelConfig = $derived(store.ariaLabelConfig);
+
 
   let prevConnections: Map<string, HandleConnection> | null = null;
   $effect.pre(() => {
@@ -227,6 +229,7 @@ The Handle component is the part of a node that can be used to connect nodes.
   onkeypress={() => {}}
   {style}
   role="button"
+  aria-label={ariaLabelConfig[`handle.ariaLabel`]}
   tabindex="-1"
   {...rest}
 >

packages/svelte/src/lib/components/NodeWrapper/NodeWrapper.svelte

@@ -85,6 +85,7 @@
   let prevTargetPosition: Position | undefined = targetPosition;
 
   let NodeComponent = $derived(store.nodeTypes[type] ?? DefaultNode);
+  let ariaLabelConfig = $derived(store.ariaLabelConfig);
 
   let connectableContext: ConnectableContext = {
     get value() {
@@ -188,11 +189,11 @@
     ) {
       // prevent default scrolling behavior on arrow key press when node is moved
       event.preventDefault();
-
+      store.ariaLiveMessage = ariaLabelConfig['node.a11yDescription.ariaLiveMessage']({
-      store.ariaLiveMessage = `Moved selected node ${event.key
+        direction: event.key.replace('Arrow', '').toLowerCase(),
-        .replace('Arrow', '')
+        x: ~~node.internals.positionAbsolute.x,
-        .toLowerCase()}. New position, x: ${node.internals.positionAbsolute.x}, y: ${node.internals.positionAbsolute.y}`;
+        y: ~~node.internals.positionAbsolute.y
-
+      });
       store.moveSelectedNodes(arrowKeyDiffs[event.key], event.shiftKey ? 4 : 1);
     }
   }

packages/svelte/src/lib/container/SvelteFlow/Wrapper.svelte

@@ -92,6 +92,7 @@
     noDragClass,
     noPanClass,
     noWheelClass,
+    ariaLabelConfig,
     ...divAttributes
   } = $derived(rest);
   /* eslint-enable @typescript-eslint/no-unused-vars */

packages/svelte/src/lib/container/SvelteFlow/types.ts

@@ -20,7 +20,8 @@ import type {
   OnConnectEnd,
   OnReconnect,
   OnReconnectStart,
-  OnReconnectEnd
+  OnReconnectEnd,
+  AriaLabelConfig
 } from '@xyflow/system';
 
 import type {
@@ -471,4 +472,9 @@ export type SvelteFlowProps<
     onselectionstart?: (event: PointerEvent) => void;
     /** This event handler gets called when the user finishes dragging a selection box */
     onselectionend?: (event: PointerEvent) => void;
+    /**
+     * Configuration for customizable labels, descriptions, and UI text. Provided keys will override the corresponding defaults.
+     * Allows localization, customization of ARIA descriptions, control labels, minimap labels, and other UI strings.
+     */
+    ariaLabelConfig?: Partial<AriaLabelConfig>;
   };

packages/svelte/src/lib/index.ts

@@ -112,7 +112,8 @@ export {
   type ResizeParamsWithDirection,
   type ResizeDragEvent,
   type IsValidConnection,
-  type NodeConnection
+  type NodeConnection,
+  type AriaLabelConfig
 } from '@xyflow/system';
 
 // system utils

packages/svelte/src/lib/plugins/Controls/Controls.svelte

@@ -46,6 +46,7 @@
   );
   let minZoomReached = $derived(store.viewport.zoom <= store.minZoom);
   let maxZoomReached = $derived(store.viewport.zoom >= store.maxZoom);
+  let ariaLabelConfig = $derived(store.ariaLabelConfig);
   let orientationClass = $derived(orientation === 'horizontal' ? 'horizontal' : 'vertical');
 
   const onZoomInHandler = () => {
@@ -72,7 +73,7 @@
   class={['svelte-flow__controls', orientationClass, className]}
   {position}
   data-testid="svelte-flow__controls"
-  aria-label={ariaLabel ?? 'Svelte Flow controls'}
+  aria-label={ariaLabelConfig['controls.ariaLabel']}
   {style}
   {...rest}
 >
@@ -83,8 +84,8 @@
     <ControlButton
       onclick={onZoomInHandler}
       class="svelte-flow__controls-zoomin"
-      title="zoom in"
+      title={ariaLabelConfig['controls.zoomIn.ariaLabel']}
-      aria-label="zoom in"
+      aria-label={ariaLabelConfig['controls.zoomIn.ariaLabel']}
       disabled={maxZoomReached}
       {...buttonProps}
     >
@@ -93,8 +94,8 @@
     <ControlButton
       onclick={onZoomOutHandler}
       class="svelte-flow__controls-zoomout"
-      title="zoom out"
+      title={ariaLabelConfig['controls.zoomOut.ariaLabel']}
-      aria-label="zoom out"
+      aria-label={ariaLabelConfig['controls.zoomOut.ariaLabel']}
       disabled={minZoomReached}
       {...buttonProps}
     >
@@ -105,8 +106,8 @@
     <ControlButton
       class="svelte-flow__controls-fitview"
       onclick={onFitViewHandler}
-      title="fit view"
+      title={ariaLabelConfig['controls.fitView.ariaLabel']}
-      aria-label="fit view"
+      aria-label={ariaLabelConfig['controls.fitView.ariaLabel']}
       {...buttonProps}
     >
       <FitViewIcon />
@@ -116,8 +117,8 @@
     <ControlButton
       class="svelte-flow__controls-interactive"
       onclick={onToggleInteractivity}
-      title="toggle interactivity"
+      title={ariaLabelConfig['controls.interactive.ariaLabel']}
-      aria-label="toggle interactivity"
+      aria-label={ariaLabelConfig['controls.interactive.ariaLabel']}
       {...buttonProps}
     >
       {#if isInteractive}<UnlockIcon />{:else}<LockIcon />{/if}

packages/svelte/src/lib/plugins/Minimap/Minimap.svelte

@@ -21,7 +21,7 @@
 
   let {
     position = 'bottom-right',
-    ariaLabel = 'Mini map',
+    ariaLabel,
     nodeStrokeColor = 'transparent',
     nodeColor,
     nodeClass = '',
@@ -42,6 +42,7 @@
   }: MiniMapProps = $props();
 
   let store = $derived(useStore());
+  let ariaLabelConfig = $derived(store.ariaLabelConfig);
 
   const nodeColorFunc = nodeColor === undefined ? undefined : getAttrFunction(nodeColor);
   const nodeStrokeColorFunc = getAttrFunction(nodeStrokeColor);
@@ -113,7 +114,9 @@
         zoomable
       }}
     >
-      {#if ariaLabel}<title id={labelledBy}>{ariaLabel}</title>{/if}
+      {#if ariaLabel ?? ariaLabelConfig['minimap.ariaLabel']}
+        <title id={labelledBy}>{ariaLabel ?? ariaLabelConfig['minimap.ariaLabel']}</title>
+      {/if}
 
       {#each store.nodes as userNode (userNode.id)}
         {@const node = store.nodeLookup.get(userNode.id)}

packages/svelte/src/lib/store/initial-store.svelte.ts

@@ -7,6 +7,7 @@ import {
   getViewportForBounds,
   updateConnectionLookup,
   initialConnection,
+  mergeAriaLabelConfig,
   type SelectionRect,
   type SnapGrid,
   type MarkerProps,
@@ -32,7 +33,8 @@ import {
   type Handle,
   type OnReconnect,
   type OnReconnectStart,
-  type OnReconnectEnd
+  type OnReconnectEnd,
+  type AriaLabelConfig
 } from '@xyflow/system';
 
 import DefaultNode from '$lib/components/nodes/DefaultNode.svelte';
@@ -289,6 +291,9 @@ export function getInitialStore<NodeType extends Node = Node, EdgeType extends E
     noPanClass: string = $derived(signals.props.noPanClass ?? 'nopan');
     noDragClass: string = $derived(signals.props.noDragClass ?? 'nodrag');
     noWheelClass: string = $derived(signals.props.noWheelClass ?? 'nowheel');
+    ariaLabelConfig: AriaLabelConfig = $derived(
+      mergeAriaLabelConfig(signals.props.ariaLabelConfig)
+    );
 
     // _viewport is the internal viewport.
     // when binding to viewport, we operate on signals.viewport instead

packages/system/src/constants.ts

@@ -36,3 +36,29 @@ export const infiniteExtent: CoordinateExtent = [
 ];
 
 export const elementSelectionKeys = ['Enter', ' ', 'Escape'];
+
+export const defaultAriaLabelConfig = {
+  'node.a11yDescription.default':
+    'Press enter or space to select a node. Press delete to remove it and escape to cancel.',
+  'node.a11yDescription.keyboardDisabled':
+    'Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.',
+  'node.a11yDescription.ariaLiveMessage': ({ direction, x, y }: { direction: string; x: number; y: number }) =>
+    `Moved selected node ${direction}. New position, x: ${x}, y: ${y}`,
+  'edge.a11yDescription.default':
+    'Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.',
+
+  // Control elements
+  'controls.ariaLabel': 'Control Panel',
+  'controls.zoomIn.ariaLabel': 'Zoom In',
+  'controls.zoomOut.ariaLabel': 'Zoom Out',
+  'controls.fitView.ariaLabel': 'Fit View',
+  'controls.interactive.ariaLabel': 'Toggle Interactivity',
+
+  // Mini map
+  'minimap.ariaLabel': 'Mini Map',
+
+  // Handle
+  'handle.ariaLabel': 'Handle',
+};
+
+export type AriaLabelConfig = typeof defaultAriaLabelConfig;

packages/system/src/utils/general.ts

@@ -16,6 +16,8 @@ import type {
 import { type Viewport } from '../types';
 import { getNodePositionWithOrigin, isInternalNodeBase } from './graph';
 
+import { defaultAriaLabelConfig, type AriaLabelConfig } from '../constants';
+
 export const clamp = (val: number, min = 0, max = 1): number => Math.min(Math.max(val, min), max);
 
 export const clampPosition = (
@@ -418,3 +420,7 @@ export function withResolvers<T>(): {
   });
   return { promise, resolve, reject };
 }
+
+export function mergeAriaLabelConfig(partial?: Partial<AriaLabelConfig>): AriaLabelConfig {
+  return { ...defaultAriaLabelConfig, ...(partial || {}) };
+}