Accessibility / Keyboard Navigation Guide

Shadcn Table tries to get the basics of data grid accessibility right out of the box. But since you can easily add event handlers to just about any interaction inside of the table, you can heavily customize the accessibility of your table to your needs too.

Relevant Table OptionsCopy Anchor Link

Keyboard NavigationCopy Anchor Link

Shadcn Table has a table option that is true by default: enableKeyboardShortcuts

enableKeyboardShortcutsCopy Anchor Link

This option enables the following keyboard shortcuts:

• Tab - Moves the focus to the next cell or element in the table (standard browser behavior)
• Arrow Up - Moves the focus 1 cell up
• Arrow Down - Moves the focus 1 cell down
• Arrow Left - Moves the focus 1 cell left
• Arrow Right - Moves the focus 1 cell right
• Home - Moves the focus to the first cell in the current row
• End - Moves the focus to the last cell in the current row
• Page Up - Moves the focus to the first cell in the current column
• Page Down - Moves the focus to the last cell in the current column
• Ctrl/Cmd + Home - Moves the focus to the first cell in the table (top left in left-to-right languages)
• Ctrl/Cmd + End - Moves the focus to the last cell in the table (bottom right in left-to-right languages)
• Enter - Performs certain actions in the currently focused cell such as sorting, row selection, row expansion, row pinning, etc.
• Space - Also performs certain actions in the currently focused cell such as sorting, row selection, row expansion, row pinning, etc.
• Ctrl/Cmd + Enter - Opens column actions menu on a header
• Escape - Exits full screen mode

A tabIndex={0} is also automatically added to all cells, headers, and footers when enableKeyboardShortcuts is enabled to allow for keyboard focus.

Custom Keyboard ShortcutsCopy Anchor Link

You do not have to use the provided keyboard shortcuts. You can turn off enableKeyboardShortcuts and add your own keyboard shortcuts using the onKeyDown event handler on all of the table cells (or any other element).

You can also add custom focus styles to any element using the className prop.

const table = useShadcnTable({
  columns,
  data,
  //add custom keyboard shortcuts
  defaultColumn: {
    //header
    stTableHeadCellProps: {
      onKeyDown: (event) => {
        if (event.key === 't' && event.metaKey) {
          alert('You pressed the custom shortcut!');
        }
      },
      tabIndex: 0, //allow for keyboard focus
    },
    //body
    stTableBodyCellProps: {
      onKeyDown: (event) => {
        if (event.key === 't' && event.metaKey) {
          alert('You pressed the custom shortcut!');
        }
      },
      //add custom focus styles (or just `focus:` if you want all focus events to be visible)
      className:
        'focus-visible:outline-2 focus-visible:outline-red-500 focus-visible:-outline-offset-2',
      tabIndex: 0, //allow for keyboard focus
    },
  },
  enableKeyboardShortcuts: false, //turn off default keyboard shortcuts from ST
});

Custom Focus StylesCopy Anchor Link

An outline is automatically added to all elements when they are focused. The outline uses the shadcn ring color, so you can easily customize its color by overriding the --ring CSS variable on the table.

const table = useShadcnTable({
  columns,
  data,
  stTableLayoutProps: {
    style: { '--ring': 'limegreen' } as React.CSSProperties,
  },
});

Or, of course, you can just use the className or style props to override any styles you want, just like any other style override in ST.

const table = useShadcnTable({
  columns,
  data,
  defaultColumn: {
    stTableBodyCellProps: {
      className:
        'focus-visible:outline-4 focus-visible:outline-red-500 focus-visible:-outline-offset-4',
    },
  },
});

Full Screen ModeCopy Anchor Link

A focus trap is applied to the table when in full screen mode. This is to prevent the user from navigating outside of the table when using the arrow keys.

The user can exit full screen mode by pressing Escape.