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

# Migrate TextBlock to the Polaris paragraph component

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

***

## Updated properties

The following properties are different in the Polaris paragraph component.

### inline​Alignment

The previous `TextBlock` `inlineAlignment` prop is now called [`textAlign`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-textalign). The accepted values are unchanged.

| Previous value | New value |
| - | - |
| `inlineAlignment="start"` | `textAlign="start"` |
| `inlineAlignment="center"` | `textAlign="center"` |
| `inlineAlignment="end"` | `textAlign="end"` |

## Migrating inlineAlignment to textAlign

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-paragraph textAlign="end">Total: $99.99</s-paragraph>
  );
}
```

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

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

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

function Extension() {
  return (
    <TextBlock inlineAlignment="end">Total: $99.99</TextBlock>
  );
}
```

### size

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

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` | `'paragraph'` | Default type, can be omitted. |
| `'small'` | `'small'` | Use `type="small"`. |

## Migrating size 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-paragraph type="small">
      Fine print or disclaimer text
    </s-paragraph>
  );
}
```

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

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

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

function Extension() {
  return (
    <TextBlock size="small">
      Fine print or disclaimer text
    </TextBlock>
  );
}
```

***

## Removed properties

### appearance

The Polaris paragraph component no longer supports `appearance`. Use [`color`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-color) and [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#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'` | Removed | Interactive elements like [`<s-link>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link) are styled with the accent treatment automatically. |

## 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-paragraph color="subdued">
        Secondary information
      </s-paragraph>
      <s-paragraph tone="success">
        Your order was successful
      </s-paragraph>
    </>
  );
}
```

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

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

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

function Extension() {
  return (
    <>
      <TextBlock appearance="subdued">
        Secondary information
      </TextBlock>
      <TextBlock appearance="success">
        Your order was successful
      </TextBlock>
    </>
  );
}
```

### emphasis

The Polaris paragraph component no longer supports `emphasis` directly. Wrap content in [`<s-text>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text) with the appropriate `type` to apply emphasis.

| Previous value | New pattern |
| - | - |
| `emphasis="bold"` | Wrap in `<s-text type="strong">` |
| `emphasis="italic"` | Wrap in `<s-text type="offset">` |

## Migrating emphasis

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-paragraph>
      <s-text type="strong">Important information</s-text>
    </s-paragraph>
  );
}
```

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

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

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

function Extension() {
  return (
    <TextBlock emphasis="bold">
      Important information
    </TextBlock>
  );
}
```

***

## New properties

The Polaris paragraph 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/paragraph#properties-propertydetail-color) | `'subdued'` \| `'base'` | Text color. |
| [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-tone) | `'auto'` \| `'info'` \| `'success'` \| `'warning'` \| `'critical'` \| `'custom'` | Semantic tone. |
| [`accessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-accessibilityvisibility) | `'visible'` \| `'hidden'` \| `'exclusive'` | Controls visibility for assistive technologies. |
| [`dir`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-dir) | `'ltr'` \| `'rtl'` \| `'auto'` | Text direction. |
| [`lang`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/paragraph#properties-propertydetail-lang) | `string` | Language of the content. |

***