---
title: Migrate Text from Polaris React
description: Learn how to migrate Polaris React Text to Polaris web components.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/text'
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/text.md
api_name: app-home
---

# Migrate Text from Polaris React

Choose `s-heading`, `s-paragraph`, or `s-text` from the content's semantics, not the old visual variant. Preserve heading order and readable paragraph structure.

***

## Choose the destination

| Polaris React | Polaris web components | Migration type |
| - | - | - |
| `Text` | `s-text`, `s-paragraph`, or `s-heading`, based on semantics | Direct |

***

## Map text properties

| Polaris React | Polaris web components | Migration notes |
| - | - | - |
| `as="h1"` through `as="h6"` | `s-page heading`, `s-section heading`, or `s-heading` | The destination has no level property. Heading level is determined automatically by page and section nesting, so rebuild the semantic section hierarchy instead of copying `h1`–`h6` values. |
| `as="p"` or inline `as="span"` | `s-paragraph` or `s-text` | Choose paragraph or inline semantics from the content. |
| Strong variants, `tone`, and `truncate` | `type="strong"`, supported tone or color, and `lineClamp` where available | Map by meaning and keep required content accessible. |

***

## Migrate the call site

1. Inventory every `Text` call site and record the content, state, events, and accessibility behavior it uses.

2. Open the linked Polaris web component reference and map only documented properties, slots, and events.

3. Move unsupported responsibilities into adjacent content or app state instead of passing old props through.

4. After verification, remove the `Text` import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Prefer the `heading` property on `s-page` or `s-section` when the text names that region. Use `s-heading` for a heading in a custom layout, nested in the section whose content it introduces. Don't use visual placement alone to imply a heading level.

***

## Preserve these behaviors

* Accessible names, semantics, and keyboard behavior.
* Visible content plus disabled, loading, selected, or error state that affects the task.
* Click, change, submit, and navigation behavior used by app logic.

***

## Test and remove Polaris React

Test every migrated `Text` state used by the app. For interactive destinations, verify keyboard operation, focus, and accessible naming. For content destinations, verify document structure and alternative text where applicable. Compare behavior rather than pixel-for-pixel styling.

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.

***

## Migration example

## Migrating Text

##### Polaris web components

```tsx
export function TextMigrationExample() {
  return (
    <><s-paragraph color="subdued">Product description</s-paragraph></>
  );
}
```

##### Polaris React

```tsx
import {Text} from '@shopify/polaris';


export function TextMigrationExample() {

  return (
    <Text as="p" variant="bodyMd" tone="subdued">Product description</Text>
  );
}
```

***