Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Header

The header area appears at the top of the checkout page, directly below the store logo and navigation. Extensions in this area add high-visibility content to the checkout experience that buyers see immediately on page load.

Anchor to Use casesUse cases

Sitewide promotion banners: Display time-limited offers like free shipping thresholds or volume discounts based on the buyer's cart total.
Loyalty program status: Show the buyer's loyalty points and how many they'll earn from the current purchase, with account creation prompts for new customers.
Discount code automation: Detect when a buyer qualifies for an automatic discount and apply it, displaying a confirmation banner with the savings amount.
Geo-targeted messaging: Display region-specific content like customs notices for international orders or currency conversion reminders based on the buyer's location.

Anchor to Header targetHeader target

Use this static extension target to extend the area directly below the checkout header. This target supports the full checkout component set, including form fields, banners, images, and interactive elements. The examples demonstrate using API methods for cart mutations and API properties for reading checkout state.

Anchor to Checkout header ,[object Object]Checkout header target

purchase.checkout.header.render-after

Adds persistent content directly below the checkout header. Like all checkout targets, this target has write access through API methods for cart lines, discount codes, gift cards, notes, attributes, metafields, and shipping address changes.

Extensions also have read access through API properties to shop information, buyer identity, cost breakdowns, cart lines, delivery groups, discount codes, localization, and other checkout state.

Support

Components (59)

APIs (25)

Examples

import {

reactExtension,

Banner,

useTotalAmount,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.header.render-after',

() => <Extension />,

);

const FREE_SHIPPING_THRESHOLD = 75;

function Extension() {

const totalAmount = useTotalAmount();

const total = Number(totalAmount.amount);

const remaining =

FREE_SHIPPING_THRESHOLD - total;

if (remaining <= 0) {

return (

You've qualified for free shipping!

</Banner>

);

}

return (

Add ${remaining.toFixed(2)} more for free

shipping.

</Banner>

);

}

Examples

Description

Create a header extension that calculates the gap between the buyer's cart total and a free shipping threshold, then displays a promotional banner with the remaining amount.

React

import {
  reactExtension,
  Banner,
  useTotalAmount,
} from '@shopify/ui-extensions-react/checkout';

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

const FREE_SHIPPING_THRESHOLD = 75;

function Extension() {
  const totalAmount = useTotalAmount();
  const total = Number(totalAmount.amount);
  const remaining =
    FREE_SHIPPING_THRESHOLD - total;

  if (remaining <= 0) {
    return (
      <Banner status="success">
        You've qualified for free shipping!
      </Banner>
    );
  }

  return (
    <Banner>
      Add ${remaining.toFixed(2)} more for free
      shipping.
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/checkout';

const FREE_SHIPPING_THRESHOLD = 75;

export default extension(
  'purchase.checkout.header.render-after',
  (root, api) => {
    const container = root.createFragment();

    function update() {
      container.replaceChildren();

      const totalAmount =
        api.cost.totalAmount.current;
      const total = Number(totalAmount.amount);
      const remaining =
        FREE_SHIPPING_THRESHOLD - total;

      if (remaining <= 0) {
        container.appendChild(
          root.createComponent(
            Banner,
            {status: 'success'},
            "You've qualified for free shipping!",
          ),
        );
      } else {
        container.appendChild(
          root.createComponent(
            Banner,
            {},
            `Add $${remaining.toFixed(2)} more for free shipping.`,
          ),
        );
      }
    }

    api.cost.totalAmount.subscribe(update);
    update();
    root.appendChild(container);
  },
);

Anchor to Best practicesBest practices

Reserve space for dynamic content: Layout shifts are highly visible in the header. If you load data asynchronously, use a skeleton paragraph or spinner to hold space while content loads.

Was this page helpful?