Migrate Collapsible from Polaris React

Polaris web components don't have a direct Collapsible. Use native details and summary for a merchant-controlled disclosure. Use conditional rendering when app state determines whether content exists at all.

Anchor to Migrate a disclosureMigrate a disclosure

Polaris web components

function AdvancedSettings() {

return (

<summary>Advanced settings</summary>

<s-box paddingBlockStart="base">

<s-text-field

label="Webhook URL"

name="webhookUrl"

details="Send order events to this HTTPS endpoint"

</s-box>

</details>

);

}

Polaris React

import {Button, Collapsible, TextField} from '@shopify/polaris';

function AdvancedSettings() {

const [open, setOpen] = useState(false);

return (

<Button

onClick={() => setOpen((value) => !value)}

ariaExpanded={open}

ariaControls="advanced-settings"

Advanced settings

</Button>

</Collapsible>

</>

);

}

Anchor to Replace Collapsible propertiesReplace Collapsible properties

Polaris React	Destination	Migration notes
`open`	`open` on `details`, or the conditional-rendering predicate	Use controlled state only when other app behavior needs it.
`id`	Remove for native disclosure, or retain for app logic	`summary` already controls its containing `details`.
`transition`	Remove	Don't reproduce animation timing before semantics and state are correct.
`expandOnPrint`	Print-specific app styles only when the content must print	Verify the actual printed workflow.
`children`	Disclosure content or conditionally rendered content	Don't hide required primary task content.

Use conditional rendering for permission-gated, mode-specific, or unavailable content. Use hidden only when keeping DOM state is intentional and test that hidden controls can't receive focus.

Don't use a disclosure for validation errors, primary actions, or information merchants must read to complete the task. Keep those visible.

Anchor to Test the migrationTest the migration

Toggle with pointer, Enter, and Space, and verify the expanded state is announced.
Tab through closed and open states and confirm hidden controls aren't focusable.
Preserve or intentionally reset field values when closing.
Test browser reload and deep-link restoration if open state was persisted.
Print the page when the old call site used expandOnPrint.

Anchor to Remove Polaris ReactRemove Polaris React

Remove Collapsible, manual ariaExpanded and ariaControls wiring replaced by native disclosure, and transition helpers with no remaining caller. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Migration exampleMigration example

Migrating Collapsible

import {useEffect, useRef, useState} from 'react';

export function CollapsibleMigrationExample() {

const [open, setOpen] = useState(true);

const button = useRef<HTMLElementTagNameMap['s-button']>(null);

useEffect(() => {

button.current?.setAttribute('aria-expanded', String(open));

button.current?.setAttribute('aria-controls', 'shipping-details');

}, [open]);

return (

<s-stack gap="small" alignItems="start">

<s-button ref={button} onClick={() => setOpen((expanded) => !expanded)}>

Shipping details

</s-button>

<s-text>Ships in 2–3 days.</s-text>

</div>

</s-stack>

);

}

import {useState} from 'react';

import {Button, Collapsible, Text} from '@shopify/polaris';

export function CollapsibleMigrationExample() {

const [open, setOpen] = useState(true);

return (

<Button onClick={() => setOpen(!open)}>Shipping details</Button>

<Text as="p">Ships in 2 to 3 days.</Text>

</Collapsible>

</>

);

}

Polaris web components

import {useEffect, useRef, useState} from 'react';

export function CollapsibleMigrationExample() {
  const [open, setOpen] = useState(true);
  const button = useRef<HTMLElementTagNameMap['s-button']>(null);

  useEffect(() => {
    button.current?.setAttribute('aria-expanded', String(open));
    button.current?.setAttribute('aria-controls', 'shipping-details');
  }, [open]);

  return (
    <s-stack gap="small" alignItems="start">
      <s-button ref={button} onClick={() => setOpen((expanded) => !expanded)}>
        Shipping details
      </s-button>
      <div id="shipping-details" hidden={!open}>
        <s-text>Ships in 2–3 days.</s-text>
      </div>
    </s-stack>
  );
}

Polaris React

import {useState} from 'react';
import {Button, Collapsible, Text} from '@shopify/polaris';

export function CollapsibleMigrationExample() {
  const [open, setOpen] = useState(true);
  return (
    <>
      <Button onClick={() => setOpen(!open)}>Shipping details</Button>
      <Collapsible open={open} id="shipping">
        <Text as="p">Ships in 2 to 3 days.</Text>
      </Collapsible>
    </>
  );
}

Preview

Anchor to Related guidanceRelated guidance

Was this page helpful?