---
title: Migrate Disclosure to the Polaris details component
description: >-
  Learn how to migrate the Disclosure component to Polaris web components in
  checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/disclosure
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/disclosure.md
---

# Migrate Disclosure to the Polaris details component

The Polaris details component provides expandable and collapsible content sections. It replaces the previous [`Disclosure`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/interactive/disclosure) component and is available as [`<s-details>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details) in API versions 2025-10 and newer.

The previous `Disclosure` component paired an activator child (a `Button`, `Pressable`, `Checkbox`, or `Switch` with `toggles`) with content children that expanded or collapsed. The Polaris `<s-details>` component is a single element that renders both summary and content through its own children.

***

## Updated patterns

### Basic disclosure

The previous pattern of using `Disclosure` as a wrapper with a `Button toggles` activator is now handled by an `<s-button>` with `command="--toggle"` and `commandFor` pointing at an `<s-details>` element by `id`. The button keeps the same visual treatment as before, while `<s-details>` carries the disclosed content.

## Migrating basic disclosure to s-details

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-button command="--toggle" commandFor="order-details" variant="primary">
        Show order details
      </s-button>
      <s-details id="order-details">
        <s-text>Your order includes free shipping and gift wrapping.</s-text>
      </s-details>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Button,
  Disclosure,
  Text,
  View,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Disclosure>
      <Button toggles="order-details">Show order details</Button>
      <View id="order-details">
        <Text>Your order includes free shipping and gift wrapping.</Text>
      </View>
    </Disclosure>
  );
}
```

If you'd prefer the native disclosure widget over a button activator, `<s-details>` also supports an `<s-summary>` child that renders an inline expandable summary.

### Separate activator with command

If you need a trigger element that is separate from the content (for example, a `Checkbox` or `Switch` toggling a content block), use [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button#properties-propertydetail-command) and [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button#properties-propertydetail-commandfor) on the activator, pointing at the `<s-details>` by `id`.

## Migrating separate activator pattern

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-switch
        label="Add gift wrapping"
        command="--toggle"
        commandFor="gift-options"
      />
      <s-details id="gift-options">
        <s-text>
          We'll wrap your order in premium gift paper with a handwritten note.
        </s-text>
      </s-details>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Disclosure,
  Switch,
  Text,
  View,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Disclosure>
      <Switch toggles="gift-options">Add gift wrapping</Switch>
      <View id="gift-options">
        <Text>
          We'll wrap your order in premium gift paper with a handwritten note.
        </Text>
      </View>
    </Disclosure>
  );
}
```

***

## Updated properties

The following properties are different in the Polaris details component.

### default​Open

The previous `Disclosure` `defaultOpen` prop accepted `boolean`, `string`, or `string[]` values to control which content blocks start expanded. The Polaris [`defaultOpen`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#properties-propertydetail-defaultopen) prop is a simple `boolean`.

| Previous value | New value | Migration notes |
| - | - | - |
| `{true}` | `defaultOpen` | No change for simple boolean usage. |
| `"section-id"` | `defaultOpen` | Use one `<s-details>` per section and set `defaultOpen` on each one that should start expanded. |
| `{["id-1", "id-2"]}` | `defaultOpen` on each `<s-details>` | Multiple open sections require separate `<s-details>` elements. |

### transition

The previous `Disclosure` `transition` prop is now called [`toggleTransition`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#properties-propertydetail-toggletransition).

| Previous value | New value | Migration notes |
| - | - | - |
| `'none'` | `toggleTransition="none"` | Disables the transition animation. |
| Not set | `toggleTransition="auto"` | `'auto'` is the default. |

### open and on​Toggle

The previous controlled pattern using `open` and `onToggle` is now handled through the [`open`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#properties-propertydetail-open) property and the [`toggle`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#events-propertydetail-toggle) / [`aftertoggle`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#events-propertydetail-aftertoggle) events.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `open={state}` + `onToggle` | `.open` property + `onToggle` / `onAfterToggle` events | `open` is a JS property that does not reflect to an attribute. |

## Migrating controlled disclosure

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

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

  return (
    <>
      <s-button onClick={() => setOpen(!open)} variant="primary">
        {open ? 'Hide' : 'Show'} details
      </s-button>
      <s-details open={open} onToggle={(event) => setOpen(event.newState === 'open')}>
        <s-text>Your order includes free shipping.</s-text>
      </s-details>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {useState} from 'react';
import {
  reactExtension,
  Button,
  Disclosure,
  Text,
  View,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

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

  return (
    <Disclosure open={open} onToggle={(openIds) => setOpen(openIds.length > 0)}>
      <Button toggles="details">
        {open ? 'Hide' : 'Show'} details
      </Button>
      <View id="details">
        <Text>Your order includes free shipping.</Text>
      </View>
    </Disclosure>
  );
}
```

***

## Removed properties

The following properties from the previous `Disclosure` component are no longer needed:

* `toggles` on activator children — replaced by `command` and `commandFor` attributes on the activator element, or by using `<s-summary>` inside `<s-details>`. See the [separate activator pattern](#separate-activator-with-command) above.

***

## New properties

The Polaris details component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`toggleTransition`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#properties-propertydetail-toggletransition) | `'auto'` \| `'none'` | Controls the expand/collapse animation. Default is `'auto'`. Replaces the previous `transition` prop. |

***