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

# Migrate to the Polaris text component

The Polaris text component renders inline text with semantic meaning and styling. It replaces the previous [`Text`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/typography-and-content/text) component and is available as [`<s-text>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris text component.

### emphasis

The previous `Text` `emphasis` prop is now called [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-type).

| Previous value | New value | Migration notes |
| - | - | - |
| `'bold'` | `type="strong"` | Use `type="strong"`. |
| `'italic'` | `type="offset"` | Use `type="offset"`. |

## Migrating emphasis to type

##### Latest (Preact)

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

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

function Extension() {
  return <s-text type="strong">Total: $99.99</s-text>;
}
```

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

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

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

function Extension() {
  return <Text emphasis="bold">Total: $99.99</Text>;
}
```

### accessibility​Role

The previous `Text` `accessibilityRole` prop has been replaced with [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-type) for string roles, and separate components for object roles.

**String roles:**

| Previous role | New pattern |
| - | - |
| `'address'` | `type="address"` |
| `'deletion'` | `type="redundant"` |
| `'marking'` | `type="mark"` |
| `'offset'` | `type="offset"` |
| `'stress'` | `type="offset"` |
| `'strong'` | `type="strong"` |

**Object roles:**

| Previous pattern | New pattern |
| - | - |
| `accessibilityRole={{type: 'abbreviation', for: '...'}}` | Use `<s-abbreviation title="...">` |
| `accessibilityRole={{type: 'datetime', machineReadable: '...'}}` | Use `<s-time dateTime="...">` |
| `accessibilityRole={{type: 'directional-override', direction: '...'}}` | Use `dir` prop on `<s-text>` |

## Migrating accessibilityRole (string)

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-text type="address">
      123 Main St, Toronto, ON
    </s-text>
  );
}
```

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

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

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

function Extension() {
  return (
    <Text accessibilityRole="address">
      123 Main St, Toronto, ON
    </Text>
  );
}
```

## Migrating accessibilityRole (object)

##### Latest (Preact)

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

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

function Extension() {
  return (
    <>
      <s-abbreviation title="Hypertext Markup Language">
        HTML
      </s-abbreviation>
      <s-time dateTime="2024-01-15">January 15, 2024</s-time>
      <s-text dir="rtl">שלום</s-text>
    </>
  );
}
```

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

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

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

function Extension() {
  return (
    <>
      <Text
        accessibilityRole={{
          type: 'abbreviation',
          for: 'Hypertext Markup Language',
        }}
      >
        HTML
      </Text>
      <Text
        accessibilityRole={{
          type: 'datetime',
          machineReadable: '2024-01-15',
        }}
      >
        January 15, 2024
      </Text>
      <Text
        accessibilityRole={{
          type: 'directional-override',
          direction: 'rtl',
        }}
      >
        שלום
      </Text>
    </>
  );
}
```

### visibility

The previous `visibility="hidden"` is now [`accessibilityVisibility="exclusive"`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-accessibilityvisibility).

| Previous pattern | New pattern |
| - | - |
| `visibility="hidden"` | `accessibilityVisibility="exclusive"` |

***

## Removed properties

### appearance

The Polaris text component no longer supports `appearance`. Use [`color`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-color) and [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-tone) instead.

| Previous value | New pattern | Migration notes |
| - | - | - |
| `'subdued'` | `color="subdued"` | Use `color` prop. |
| `'info'` | `tone="info"` | Use `tone` prop. |
| `'success'` | `tone="success"` | Use `tone` prop. |
| `'warning'` | `tone="warning"` | Use `tone` prop. |
| `'critical'` | `tone="critical"` | Use `tone` prop. |
| `'decorative'` | `tone="custom"` | Use `tone="custom"`. |
| `'accent'` | `tone="auto"` | Use `tone="auto"`. |

## Migrating appearance to color and tone

##### Latest (Preact)

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

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

function Extension() {
  return (
    <>
      <s-text color="subdued">Optional</s-text>
      <s-text tone="critical">Payment failed</s-text>
    </>
  );
}
```

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

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

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

function Extension() {
  return (
    <>
      <Text appearance="subdued">Optional</Text>
      <Text appearance="critical">Payment failed</Text>
    </>
  );
}
```

### size

The Polaris text component no longer supports `size`. Use `type="small"` for small text, or [`<s-heading>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/heading) for larger text.

***

## New properties

The Polaris text component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`color`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-color) | `'subdued'` \| `'base'` | Text color. |
| [`dir`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-dir) | `'ltr'` \| `'rtl'` \| `'auto'` | Text direction. |
| [`display`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-display) | `'auto'` \| `'none'` | Controls element visibility. |
| [`lang`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-lang) | `string` | Language of the text content. |
| [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text#properties-propertydetail-tone) | `'auto'` \| `'info'` \| `'success'` \| `'warning'` \| `'critical'` \| `'custom'` | Semantic tone. |

***