Migrate TextBlock to the Polaris paragraph component

The Polaris paragraph component renders block-level text content. It replaces the previous TextBlock component and is available as <s-paragraph> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris paragraph component.

Anchor to inlineAlignmentinlineAlignment

The previous TextBlock inlineAlignment prop is now called textAlign. The accepted values are unchanged.

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>
  );
}

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>
  );
}

Anchor to sizesize

The previous TextBlock size prop is now called type.

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>
  );
}

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>
  );
}

Anchor to Removed propertiesRemoved properties

Anchor to appearanceappearance

The Polaris paragraph component no longer supports appearance. Use color and tone instead.

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>
    </>
  );
}

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>
    </>
  );
}

Anchor to emphasisemphasis

The Polaris paragraph component no longer supports emphasis directly. Wrap content in <s-text> with the appropriate type to apply emphasis.

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>
  );
}

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>
  );
}

Anchor to New propertiesNew properties

The Polaris paragraph component introduces the following new properties: