Migrate UnstyledButton from Polaris React

Use a native button for app-owned custom controls or s-clickable for a supported clickable composition. Preserve button semantics, focus visibility, and disabled behavior.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`UnstyledButton`	Native `button` or `s-clickable`	Native HTML

Anchor to Map unstyled-button behaviorMap unstyled-button behavior

Polaris React	Polaris web components	Migration notes
`onClick` and `disabled`	Native button behavior or `s-clickable` activation	Preserve keyboard activation and don't replace the button with a clickable `div`.
`accessibilityLabel`	Native `aria-label` or component `accessibilityLabel`	Prefer visible text when the control can accommodate it.
Navigation or submit behavior	A real `href` or native `button type="submit"`	Preserve browser navigation and form validation semantics.

Anchor to Migrate the call siteMigrate the call site

Choose the native element whose semantics match the UnstyledButton 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 UnstyledButton 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 UnstyledButton 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 UnstyledButton

export function UnstyledButtonMigrationExample() {

return (

<><button type="button">Custom action</button></>

);

}

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

export function UnstyledButtonMigrationExample() {

return (

<UnstyledButton onClick={() => {}}>Custom action</UnstyledButton>

);

}

Polaris web components

export function UnstyledButtonMigrationExample() {
  return (
    <><button type="button">Custom action</button></>
  );
}

Polaris React

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


export function UnstyledButtonMigrationExample() {

  return (
    <UnstyledButton onClick={() => {}}>Custom action</UnstyledButton>
  );
}

Preview

Was this page helpful?