Skip to content

Toolbar KBN Improvements: Add Info to A11y Docs #9139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
arman-boyakhchyan wants to merge 2 commits into
base: feature/26_2_toolbar-kbn-improvement
Choose a base branch
from
Open

Toolbar KBN Improvements: Add Info to A11y Docs #9139

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
18b903e
Toolbar KBN Improvements: Add Info to A11y Docs
arman-boyakhchyan Sep 3, 2026
72b5d3f
Add Fixes & Improvements
arman-boyakhchyan Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions api-reference/10 UI Components/GridBase/1 Configuration/onToolbarPreparing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,3 @@ The [properties of the toolbar](/api-reference/10%20UI%20Components/dxToolbar/1%
---

#include datagrid-ontoolbarpreparing-jquery

#include btn-open-github with {
href: "https://github.com/DevExpress-Examples/devextreme-datagrid-custom-column-chooser"
}
4 changes: 0 additions & 4 deletions api-reference/10 UI Components/dxDataGrid/1 Configuration/onToolbarPreparing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,3 @@ The [properties of the toolbar](/api-reference/10%20UI%20Components/dxToolbar/1%
---

#include datagrid-ontoolbarpreparing-jquery

#include btn-open-github with {
href: "https://github.com/DevExpress-Examples/devextreme-datagrid-custom-column-chooser"
}
4 changes: 0 additions & 4 deletions api-reference/10 UI Components/dxTreeList/1 Configuration/onToolbarPreparing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,3 @@ The [properties of the toolbar](/api-reference/10%20UI%20Components/dxToolbar/1%
---

#include datagrid-ontoolbarpreparing-jquery

#include btn-open-github with {
href: "https://github.com/DevExpress-Examples/devextreme-datagrid-custom-column-chooser"
}
8 changes: 7 additions & 1 deletion concepts/05 UI Components/CardView/10 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,20 @@ CardView offers different keyboard controls depending on the focused component a
</tr>
<tr>
<td>Left Arrow / Right Arrow</td>
<td>Moves focus between header panel items.</td>
<td>Moves focus between header panel items.<br>Moves focus between toolbar items.</td>
</tr>
<tr>
<td>Home<br/>End</td>
<td>Moves focus to the first/last item in the toolbar.</td>
</tr>
<tr>
<td>Shift + Right Arrow<br/>Shift + Left Arrow</td>
<td>Reorders the focused header item if <a href="/Documentation/ApiReference/UI_Components/dxCardView/Configuration/#allowColumnReordering">allowColumnReordering</a> is "true".</td>
</tr>
</table>

#include toolbar-kbn-behavior-defaultoptions-override

##### Sorting and Filtering

<table class="dx-table">
Expand Down
30 changes: 18 additions & 12 deletions concepts/05 UI Components/DataGrid/05 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,14 @@ DataGrid offers different keyboard controls depending on which action users want

### Navigation

[note]

- The following DataGrid features do not support the **Ctrl+Home** and **Ctrl+End** shortcuts:
- Group summaries
- Grouped data
- Expanded master-detail interfaces
- When **scrolling**.[columnRenderingMode](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/scrolling/columnRenderingMode.md '/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/scrolling/#columnRenderingMode') is *"virtual"*, the [filter row](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/filterRow '/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/filterRow/') does not support keyboard navigation.

[/note]

<table class="dx-table full-width">
<tr>
<th>Key</th>
<th>Action</th>
</tr>
<tr>
<td>Arrow Keys</td>
<td>Moves focus between cells.</td>
<td>Moves focus between cells.<br>Moves focus between toolbar items (left and right arrow keys only).</td>
</tr>
<tr>
<td>Tab<br/>Shift + Tab</td>
Expand All @@ -39,7 +29,7 @@ DataGrid offers different keyboard controls depending on which action users want
</tr>
<tr>
<td>Home<br/>End</td>
<td>Moves focus to the first/last cell of the current row.</td>
<td>Moves focus to the first/last cell of the current row.<br>Moves focus to the first/last item in the toolbar.</td>
</tr>
<tr>
<td>Ctrl + Home<br/>Ctrl + End</td>
Expand All @@ -55,6 +45,22 @@ DataGrid offers different keyboard controls depending on which action users want
</tr>
</table>

[note]

- The following DataGrid features do not support the **Ctrl+Home** and **Ctrl+End** shortcuts:
- Group summaries
- Grouped data
- Expanded master-detail interfaces
- When **scrolling**.[columnRenderingMode](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/scrolling/columnRenderingMode.md '/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/scrolling/#columnRenderingMode') is *"virtual"*, the [filter row](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/filterRow '/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/filterRow/') does not support keyboard navigation.
- To navigate between toolbar items using **Tab**, you can disable the [allowKeyboardNavigation](/Documentation/ApiReference/UI_Components/dxToolbar/Configuration/#allowKeyboardNavigation) property of the built-in DataGrid toolbar. Configure [onToolbarPreparing](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#onToolbarPreparing) as follows:

<!-- tab: JavaScript -->
onToolbarPreparing(e) {
e.toolbarOptions.allowKeyboardNavigation = false;
}

[/note]

### Column Sorting and Reordering

<table class="dx-table full-width">
Expand Down
8 changes: 7 additions & 1 deletion concepts/05 UI Components/Diagram/45 Keyboard Support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ A user can press the following keys to interact with the UI component:
</tr>
<tr>
<td>Arrow Keys</td>
<td>Moves the selected elements one grid cell in the specified direction.</td>
<td>Moves the selected elements one grid cell in the specified direction.<br>Moves focus between toolbar items (left and right arrow keys only).</td>
</tr>
<tr>
<td>Ctrl + Arrow Keys</td>
Expand All @@ -61,6 +61,10 @@ A user can press the following keys to interact with the UI component:
<td>Alt + Arrow Keys</td>
<td>Clones the selected elements.</td>
</tr>
<tr>
<td>Home<br/>End</td>
<td>Moves focus to the first/last item in a toolbar.</td>
</tr>
<tr>
<td>Left Mouse Button Drag</td>
<td>Moves the selected elements. If you realize the mouse button above a container, places the elements inside this container.</td>
Expand All @@ -87,4 +91,6 @@ A user can press the following keys to interact with the UI component:
</tr>
</table>

#include toolbar-kbn-behavior-defaultoptions-override

Refer to the following section for more information: [Work with Chart Elements](https://devexpress.github.io/dotnet-eud/interface-elements-for-web/articles/diagram.html).
13 changes: 12 additions & 1 deletion concepts/05 UI Components/HtmlEditor/03 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,16 @@ A user can use the following keys to interact with the HTML Editor component:
</tr>
<tr>
<td colspan="2">Arrow Keys</td>
<td>Navigate through the table</td>
<td>
<ul>
<li>Navigate through the table</li>
<li>Move focus between toolbar items (left and right arrow keys only).</li>
</ul>
</td>
</tr>
<tr>
<td colspan="2">Home<br>End</td>

@dmlvr dmlvr Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor: In the editor, the Home and End keys control the behavior of the caret.

<td>Move focus to the first/last item in the toolbar.</td>
</tr>
<tr>
<td>Ctrl + Shift + Up&nbsp;Arrow</td>
Expand Down Expand Up @@ -172,4 +181,6 @@ Configure [customizeModules](/api-reference/10%20UI%20Components/dxHtmlEditor/1%

---

#include toolbar-kbn-behavior-defaultoptions-override

#include common-code-register-key-handler
11 changes: 9 additions & 2 deletions concepts/05 UI Components/Scheduler/10 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@ A user can use the following keys to interact with the Scheduler component:
<tr>
<td>Scheduler UI component</td>
<td>Tab / Shift+Tab</td>
<td>Shifts focus to the next/previous appointment.</td>
<td>Shifts focus between appointments and the Scheduler toolbar.</td>

@Raushen Raushen Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The focus moves between appointment area to the toolbar area.

</tr>
<tr>
<td><a href="/Documentation/ApiReference/UI_Components/dxScheduler/Configuration/toolbar/">Toolbar</a></td>
<td>Left Arrow or Right Arrow</td>
<td>Shifts focus between toolbar items.</td>
</tr>
<tr>
<td>Scheduler UI component</td>
Expand Down Expand Up @@ -71,4 +76,6 @@ A user can use the following keys to interact with the Scheduler component:
<td>Enter or Space</td>
<td>Selects the focused element in the tooltip.</td>
</tr>
</table>
</table>

#include toolbar-kbn-behavior-defaultoptions-override
79 changes: 77 additions & 2 deletions concepts/05 UI Components/Toolbar/05 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
A user can use the following keys to interact with the Toolbar component when [allowKeyboardNavigation](/api-reference/10%20UI%20Components/dxToolbar/1%20Configuration/allowKeyboardNavigation.md '/Documentation/ApiReference/UI_Components/dxToolbar/Configuration/#allowKeyboardNavigation') is set to `true`:
You can use the following keys to interact with the Toolbar component when [allowKeyboardNavigation](/api-reference/10%20UI%20Components/dxToolbar/1%20Configuration/allowKeyboardNavigation.md '/Documentation/ApiReference/UI_Components/dxToolbar/Configuration/#allowKeyboardNavigation') is set to `true`:

<table class="dx-table">

@dmlvr dmlvr Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We implemented two-level focus for complex components; let's add descriptions for the Enter and Space keys that pass focus to the component.

When we focus button group we can change active button using up and down

Image

<tr>

@dmlvr dmlvr Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in the overflow menu we have a little different behavior, for example buttons up and down works instead of left and right

Image

Expand All @@ -21,4 +21,79 @@ A user can use the following keys to interact with the Toolbar component when [a
<td>Home / End</td>
<td>Moves focus to the first or last available Toolbar item.</td>
</tr>
</table>
</table>

This keyboard navigation behavior applies to all Toolbar instances within your app, including instances embedded in DevExtreme components such as DataGrid, FileManager, and Gantt. To modify this behavior in built-in Toolbar instances and allow users to navigate between items using **Tab**, you can disable [allowKeyboardNavigation](/Documentation/ApiReference/UI_Components/dxToolbar/Configuration/#allowKeyboardNavigation) in a [defaultOptions()](/Documentation/ApiReference/UI_Components/dxToolbar/Methods/#defaultOptionsrule) call as follows:

@dmlvr dmlvr Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure here, but technically not every toolbar have allowKeyboardNavigation: true, for example popup still have allowKeyboardNavigation false.

Usually it's is not a public toolbars, but maybe will be better to avoid "all" word here.


---

##### jQuery

<!-- tab: index.js -->
DevExpress.ui.dxToolbar.defaultOptions({
options: {
onInitialized(e) {
if ($(e.element).closest('.dx-component-name').length) {
e.component.option('allowKeyboardNavigation', false);
}
}
}
})

##### Angular

<!-- tab: app.component.ts -->
import dxToolbar from "devextreme/ui/toolbar";
import { type DxToolbarTypes } from "devextreme-angular/ui/toolbar";
// ...
export class AppComponent {
constructor() {
dxToolbar.defaultOptions({
options: {
onInitialized(e: DxToolbarTypes.InitializedEvent) {
if (e.element?.closest('.dx-component-name')) {
e.component?.option('allowKeyboardNavigation', false);
}
}
}
})
}
}

##### Vue

<!-- tab: App.vue -->
<script setup lang="ts">
import dxToolbar from "devextreme/ui/toolbar";
import { type DxToolbarTypes } from "devextreme-vue/toolbar";

dxToolbar.defaultOptions({
options: {
onInitialized(e: DxToolbarTypes.InitializedEvent) {
if (e.element?.closest('.dx-component-name')) {
e.component?.option('allowKeyboardNavigation', false);
}
}
}
});
</script>

##### React

<!-- tab: App.tsx -->
import dxToolbar from "devextreme/ui/toolbar";
import { type ToolbarTypes } from "devextreme-react/toolbar";

dxToolbar.defaultOptions({
options: {
onInitialized(e: ToolbarTypes.InitializedEvent) {
if (e.element?.closest('.dx-component-name')) {
e.component?.option('allowKeyboardNavigation', false);
}
}
}
});

---

Replace `.dx-component-name` with a component ID or class.
18 changes: 14 additions & 4 deletions concepts/05 UI Components/TreeList/05 Accessibility/15 Keyboard Navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,14 @@ TreeList offers different keyboard controls depending on what action users wish

### Navigation

[note] When **scrolling**.[columnRenderingMode](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/scrolling/columnRenderingMode.md '/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/scrolling/#columnRenderingMode') is *"virtual"*, the [filter row](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/filterRow '/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/filterRow/') does not support keyboard navigation.

<table class="dx-table full-width">
<tr>
<th>Key</th>
<th>Action</th>
</tr>
<tr>
<td>Arrow Keys</td>
<td>Moves focus between cells.</td>
<td>Moves focus between cells.<br>Moves focus between toolbar items (left and right arrow keys only).</td>
</tr>
<tr>
<td>Tab<br/>Shift + Tab</td>
Expand All @@ -35,7 +33,7 @@ TreeList offers different keyboard controls depending on what action users wish
</tr>
<tr>
<td>Home<br/>End</td>
<td>Moves focus to the first/last cell of the current row.</td>
<td>Moves focus to the first/last cell of the current row.<br>Moves focus to the first/last item in the toolbar.</td>
</tr>
<tr>
<td>Ctrl + Home<br/>Ctrl + End</td>
Expand All @@ -51,6 +49,18 @@ TreeList offers different keyboard controls depending on what action users wish
</tr>
</table>

[note]

- When **scrolling**.[columnRenderingMode](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/scrolling/columnRenderingMode.md '/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/scrolling/#columnRenderingMode') is *"virtual"*, the [filter row](/api-reference/10%20UI%20Components/GridBase/1%20Configuration/filterRow '/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/filterRow/') does not support keyboard navigation.
- To navigate between toolbar items using **Tab**, you can disable the [allowKeyboardNavigation](/Documentation/ApiReference/UI_Components/dxToolbar/Configuration/#allowKeyboardNavigation) property of the built-in TreeList toolbar. Configure [onToolbarPreparing](/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/#onToolbarPreparing) as follows:

<!-- tab: JavaScript -->
onToolbarPreparing(e) {
e.toolbarOptions.allowKeyboardNavigation = false;
}

[/note]

### Column Sorting and Reordering

<table class="dx-table full-width">
Expand Down
Loading