---
title: Migrate View to the Polaris box component
description: >-
  Learn how to migrate the View 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/view'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/view.md
---

# Migrate View to the Polaris box component

The Polaris box component is a generic container for layout and styling. It replaces the previous [`View`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/layout-and-structure/view) component and is available as [`<s-box>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris box component.

### visibility

The previous `View` `visibility` prop is now called [`accessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-accessibilityvisibility).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `visibility="hidden"` | `accessibilityVisibility="exclusive"` | Hides visually but remains accessible to assistive technologies. |

### corner​Radius

The previous `View` `cornerRadius` prop is now called [`borderRadius`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-borderradius). Some values have changed:

| Previous value | New value | Migration notes |
| - | - | - |
| `'none'` | `'none'` | No change needed. |
| `'small'` | `'small-100'` | Renamed to use token suffix. `'small'` is accepted as an alias. |
| `'base'` | `'base'` | No change needed. |
| `'large'` | `'large-100'` | Renamed to use token suffix. `'large'` is accepted as an alias. |
| `'fullyRounded'` | `'max'` | Renamed. |

For more on the scale system, see [Scale](https://shopify.dev/docs/api/checkout-ui-extensions/latest/using-polaris-components#scale).

### border

The previous `View` `border` shorthand controlled border *style* (for example, `border="dotted"`). On `<s-box>`, [`border`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-border) controls border *size* by default and accepts a token-based shorthand for size, color, and style:

| Pattern | Example | Description |
| - | - | - |
| `'{size}'` | `border="base"` | Border size only. |
| `'{size} {color}'` | `border="base base"` | Border size and color. |
| `'{size} {color} {style}'` | `border="base base dashed"` | Border size, color, and style. |

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` (single solid border) | `border="base"` | Renders a default-size border. |
| `'dotted'` | `border="base base dotted"` | Specify size and color before style. |
| `'dashed'` | `border="base base dashed"` | Specify size and color before style. |
| `'none'` | `border="none"` or omit | No border. |

### border​Width

The previous `View` `borderWidth` accepted `'base'`, `'medium'`, `'thick'`. The Polaris box [`borderWidth`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-borderwidth) accepts a reduced keyword set: `'none'`, `'base'`, `'large'`, `'large-100'`, `'large-200'`.

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` | `'base'` | No change needed. |
| `'medium'` | `'large'` | `'medium'` is removed. |
| `'thick'` | `'large-200'` | `'thick'` is removed. |

### display

The previous `View` `display` values `'inline'` and `'block'` are no longer accepted. The Polaris box [`display`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-display) accepts `'auto'` (the default) and `'none'`.

| Previous value | New value | Migration notes |
| - | - | - |
| `'block'` | `'auto'` (the default) | Omit `display` for default block-level rendering. |
| `'inline'` | Removed | Wrap inline content in [`<s-text>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text) instead. This advice applies only when migrating `display="inline"` usages — direct text children of `<s-box>` are still valid for non-inline content. |
| `'none'` | `'none'` | No change needed. |

### padding

The previous `View` `padding` prop's accepted values and multi-side shorthand format have changed.

Use the following mapping to migrate deprecated tokens:

| Previous | New |
| - | - |
| `'none'` | `'none'` |
| `'extraTight'` | `'small-400'` |
| `'tight'` | `'small-200'` |
| `'base'` | `'base'` |
| `'loose'` | `'large-200'` |
| `'extraLoose'` | `'large-500'` |

The new token scale also adds `'small-500'`, `'small-300'`, `'small-100'`, `'small'`, `'large'`, `'large-100'`, `'large-300'`, and `'large-400'`.

For more on the scale system, see [Scale](https://shopify.dev/docs/api/checkout-ui-extensions/latest/using-polaris-components#scale).

The multi-side shorthand format has also changed:

| Previous | New |
| - | - |
| Array of 2 or 4 values: `['base', 'none']` | Space-separated string with 1 to 4 values: `"base none"`. The 3-value variant `"block-start inline block-end"` is also supported. |

To set padding on a single side or axis, use the new logical-property props instead of `padding`. See [New properties](#new-properties) for the full list.

### Sizes

The size properties accept updated values in the Polaris box component. `'fill'` has been removed across all of them — use `'100%'` instead.

| Property | Previous values | New values | Migration notes |
| - | - | - | - |
| [`inlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-inlinesize) | `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | `'fill'` is removed. Use `'100%'` instead. |
| [`maxInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-maxinlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | `'fill'` is removed. Use `'100%'` instead. |
| [`minInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-mininlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | `'fill'` is removed. Use `'100%'` instead. |
| [`maxBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-maxblocksize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | `'fill'` is removed. Use `'100%'` instead. |
| [`minBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-minblocksize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | `'fill'` is removed. Use `'100%'` instead. |

### accessibility​Role

Several `accessibilityRole` values have been renamed in the Polaris box component. Update them to the new role names:

| Previous value | New value |
| - | - |
| `'complementary'` | `'aside'` |
| `'orderedList'` | `'ordered-list'` |
| `'unorderedList'` | `'unordered-list'` |
| `'listItem'` | `'list-item'` |

Other previously supported roles (`'main'`, `'header'`, `'footer'`, `'section'`, `'navigation'`, `'separator'`, `'status'`, `'alert'`) are accepted unchanged. The Polaris box also adds the following new roles:

| New role | Description |
| - | - |
| `'list-item-separator'` | Separator between list items. |
| `'generic'` | Generic container. |
| `'presentation'` | Decorative element. |
| `'none'` | No semantic role. |

## Migrating View to box

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-box
      background="subdued"
      padding="base"
      border="base"
      borderRadius="base"
    >
      Card content
    </s-box>
  );
}
```

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

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

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

function Extension() {
  return (
    <View
      background="subdued"
      padding="base"
      border="base"
      cornerRadius="base"
    >
      <Text>Card content</Text>
    </View>
  );
}
```

**Responsive values:**

If you used `Style.default().when()` to make this property responsive, container queries replace the `Style` helper. Wrap your content in `<s-query-container>` and use `@container` syntax in the property value. Learn more in [Migrate StyleHelper to container queries](https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/style-helper).

***

## Removed properties

### position

The Polaris box component no longer supports `position`.

### translate

The Polaris box component no longer supports `translate`.

### block​Alignment

The Polaris box component no longer supports `blockAlignment`. Wrap the box in [`<s-stack>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack) and use [`alignItems`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack#properties-propertydetail-alignitems) for cross-axis alignment.

## Migrating blockAlignment to alignItems

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-stack alignItems="center">
      <s-text>Centered content</s-text>
    </s-stack>
  );
}
```

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

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

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

function Extension() {
  return (
    <View blockAlignment="center">
      <Text>Centered content</Text>
    </View>
  );
}
```

### inline​Alignment

The Polaris box component no longer supports `inlineAlignment`. Wrap the box in [`<s-stack>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack) and use [`justifyContent`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack#properties-propertydetail-justifycontent) for main-axis alignment.

## Migrating alignment to stack

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-stack justifyContent="end">
      <s-button>Submit</s-button>
    </s-stack>
  );
}
```

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

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

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

function Extension() {
  return (
    <View inlineAlignment="end">
      <Button>Submit</Button>
    </View>
  );
}
```

### opacity

The Polaris box component no longer supports `opacity`. There's no workaround for this property.

### border​Color

The Polaris box component no longer supports `borderColor` as a separate property. Use the [`border`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-border) shorthand instead. See the [`border`](#border) section for the accepted patterns.

***

## New properties

The Polaris box component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`blockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-blocksize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | Adjusts the block size of the box. |
| [`borderStyle`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-borderstyle) | `'auto'` \| `'none'` \| `'solid'` \| `'dashed'` \| `'dotted'` | Sets the border style independently from the `border` shorthand. |
| [`paddingBlock`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddingblock) | Spacing token | Padding on the block axis. |
| [`paddingBlockStart`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddingblockstart) | Spacing token | Padding at the start of the block axis. |
| [`paddingBlockEnd`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddingblockend) | Spacing token | Padding at the end of the block axis. |
| [`paddingInline`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddinginline) | Spacing token | Padding on the inline axis. |
| [`paddingInlineStart`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddinginlinestart) | Spacing token | Padding at the start of the inline axis. |
| [`paddingInlineEnd`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-paddinginlineend) | Spacing token | Padding at the end of the inline axis. |

***