Migrate KeyboardKey from Polaris React

Use a native kbd element for user input such as keys or shortcuts. Keep an accompanying text description instead of relying on visual key styling alone.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`KeyboardKey`	Native `kbd` element	Native HTML

Anchor to Map keyboard key contentMap keyboard key content

Polaris React	Polaris web components	Migration notes
`children`	Native `kbd` content	Use the visible key label, such as `Esc` or `Enter`.
Key combination	Separate `kbd` elements with text separators	Make the order and modifier relationship readable.
Shortcut behavior	Existing app-owned keyboard handler	A `kbd` element documents a shortcut. It doesn't register one.

Anchor to Migrate the call siteMigrate the call site

Choose the native element whose semantics match the KeyboardKey call site.
Rebuild its accessible name and relationships before adding layout or app-owned styling.
When the element is interactive or form-associated, connect its native events and form behavior to existing app state.
After verification, remove the KeyboardKey import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Anchor to Preserve these behaviorsPreserve these behaviors

Native semantics, accessible names, and document structure.
Keyboard and form behavior supplied by the browser, where applicable.
App state, validation, and responsive layout around the element.

Anchor to Test and remove Polaris ReactTest and remove Polaris React

Test the migrated KeyboardKey with browser and accessibility semantics in mind. Verify document structure, keyboard and form behavior where applicable, accessible relationships, and app-owned state changes.

Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.

Anchor to Migration exampleMigration example

Migrating KeyboardKey

export function KeyboardKeyMigrationExample() {

return (

<><kbd>⌘ K</kbd></>

);

}

import {KeyboardKey} from '@shopify/polaris';

export function KeyboardKeyMigrationExample() {

return (

);

}

Polaris web components

export function KeyboardKeyMigrationExample() {
  return (
    <><kbd>⌘ K</kbd></>
  );
}

Polaris React

import {KeyboardKey} from '@shopify/polaris';


export function KeyboardKeyMigrationExample() {

  return (
    <KeyboardKey>⌘ K</KeyboardKey>
  );
}

Preview

Was this page helpful?