---
title: Header
description: >-
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.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/checkout/header
md: >-
https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/checkout/header.md
---
# 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](https://shopify.dev/docs/apps/build/checkout) that buyers see immediately on page load.
### Use 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.
***
## Header target
Use this [static extension target](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets#static-extension-targets) 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.
### 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 (55) APIs (24)
### Supported components
* [Abbreviation](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/abbreviation)
* [Badge](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/badge)
* [Banner](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/banner)
* [Box](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/box)
* [Button](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/button)
* [Checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/checkbox)
* [Chip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/chip)
* [Choice list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/choice-list)
* [Clickable](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clickable)
* [Clickable chip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clickable-chip)
* [Clipboard item](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clipboard-item)
* [Consent checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/consent-checkbox)
* [Consent phone field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/consent-phone-field)
* [Date field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-field)
* [Date picker](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-picker)
* [Details](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/details)
* [Divider](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/divider)
* [Drop zone](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/drop-zone)
* [Email field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/email-field)
* [Form](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/form)
* [Grid](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/grid)
* [Heading](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/heading)
* [Icon](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/icon)
* [Image](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/image)
* [Link](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/link)
* [Map](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/map)
* [Modal](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/modal)
* [Money field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/money-field)
* [Number field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/number-field)
* [Ordered list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/ordered-list)
* [Paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/paragraph)
* [Password field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/password-field)
* [Payment icon](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/payment-icon)
* [Phone field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/phone-field)
* [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/popover)
* [Press button](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/press-button)
* [Product thumbnail](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/product-thumbnail)
* [Progress](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/progress)
* [Qr code](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/qr-code)
* [Query container](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/query-container)
* [Scroll box](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/scroll-box)
* [Section](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/section)
* [Select](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/select)
* [Sheet](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/sheet)
* [Skeleton paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/skeleton-paragraph)
* [Spinner](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/spinner)
* [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/stack)
* [Switch](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/switch)
* [Text](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/text)
* [Text area](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/text-area)
* [Text field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/text-field)
* [Time](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/time)
* [Tooltip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/tooltip)
* [Unordered list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/unordered-list)
* [Url field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/url-field)
### Available APIs
* [Addresses API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/addresses-api)
* [Analytics API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/analytics-api)
* [Attributes API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/attributes-api)
* [Buyer Identity API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/buyer-identity-api)
* [Buyer Journey API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/buyer-journey-api)
* [Cart Instructions API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cart-instructions-api)
* [Cart Lines API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cart-lines-api)
* [Checkout Token API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/checkout-token-api)
* [Cost API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cost-api)
* [Customer Privacy API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/customer-privacy-api)
* [Delivery API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/delivery-api)
* [Discounts API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/discounts-api)
* [Extension API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/extension-api)
* [Gift Cards API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/gift-cards-api)
* [Localization API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/localization-api)
* [Localized Fields API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/localized-fields-api)
* [Metafields API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/metafields-api)
* [Note API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/note-api)
* [Payments API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/payments-api)
* [Session Token API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/session-token-api)
* [Settings API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/settings-api)
* [Shop API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/shop-api)
* [Storage API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/storage-api)
* [Storefront API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/storefront-api)
Examples
### 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.
##### jsx
```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
export default function extension() {
render(, document.body);
}
const FREE_SHIPPING_THRESHOLD = 75;
function Extension() {
const total = Number(
shopify.cost.totalAmount.value.amount,
);
const remaining = FREE_SHIPPING_THRESHOLD - total;
if (remaining <= 0) {
return (
You've qualified for free shipping!
);
}
return (
Add ${remaining.toFixed(2)} more for free
shipping.
);
}
```
* ####
##### Description
Detect returning customers and offer a one-click discount. This example checks \`shopify.buyerIdentity\` for a logged-in customer and uses \`shopify.applyDiscountCodeChange\` to apply a code.
##### jsx
```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';
export default function extension() {
render(, document.body);
}
function Extension() {
const [applied, setApplied] = useState(false);
const customer =
shopify.buyerIdentity?.customer.value;
const canUpdate =
shopify.instructions.value.discounts
.canUpdateDiscountCodes;
const existingCodes =
shopify.discountCodes.value;
if (
!customer ||
!canUpdate ||
applied ||
existingCodes.length > 0
) {
return null;
}
async function applyDiscount() {
const result =
await shopify.applyDiscountCodeChange({
type: 'addDiscountCode',
code: 'WELCOME_BACK_10',
});
if (result.type === 'success') {
setApplied(true);
}
}
const name =
customer.fullName ?? 'valued customer';
return (
Welcome back, {name}! As a returning
customer, you're eligible for 10% off.
Apply 10% discount
);
}
```
***
## Best practices
* **Reserve space for dynamic content**: Layout shifts are highly visible in the header. If you load data asynchronously, use a [skeleton paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/typography-and-content/skeleton-paragraph) or [spinner](https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/feedback-and-status-indicators/spinner) to hold space while content loads.
***