--- gid: 6f82c131-ab49-4757-b7cc-76f64246ae92 title: Customize the header that displays at checkout description: Learn how to customize the checkout header with checkout UI extensions and the GraphQL Admin API's checkout branding types. --- import CheckoutUiRequirements from 'app/views/partials/apps/checkout/ui-extensions/requirements.mdx' import CheckoutUiCreate from 'app/views/partials/apps/checkout/ui-extensions/create.mdx' import CheckoutQueryPublishedCheckoutProfile from 'app/views/partials/apps/checkout/ui-extensions/query-published-checkout-profile.mdx' import CheckoutUiPreview from 'app/views/partials/apps/checkout/ui-extensions/preview.mdx' import Deploy from 'app/views/partials/extensions/deploy.mdx' import CheckoutUiReference from 'app/views/partials/apps/checkout/ui-extensions/reference.mdx' <Repo extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react" /> <Repo extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js" /> <Picker name="extension"> <PickerOption name="react" /> <PickerOption name="javascript" /> </Picker> <Overview> You can customize the checkout header for custom navigation experiences, for example by hiding the default back-to-cart link and adding custom breadcrumbs. This guide explains how to customize the header using Checkout Extensibility. You'll use checkout UI extensions and the GraphQL Admin API's [checkout branding fields](/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert) to render a customized header on the **Checkout** page. Learn from an end-to-end example in this guide, and then explore the API documentation to suit your customization needs. <Notice type="shopifyPlus" title="Shopify Plus"> Checkout UI extensions and styling customizations are available only to [Shopify Plus](https://www.shopify.com/plus) merchants. </Notice> <video autoPlay muted loop controls> <source src="/assets/apps/checkout/header-footer/header.webm" type="video/webm"/> </video> ## What you'll learn In this tutorial, you'll learn how to do the following tasks: - Hide the default back-to-cart link and buyer journey breadcrumbs - Configure an extension for a single target to render in the header - Add custom breadcrumbs to the header - Deploy your extension code to Shopify </Overview> <Requirements> <Requirement href="https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plan" label="The store that you're modifying with the branding API must be on a Shopify Plus plan."> </Requirement> <CheckoutUiRequirements /> <Requirement href="/docs/api/admin-graphql" label="Your app can make authenticated requests to the GraphQL Admin API."> </Requirement> <Requirement href="https://shopify-graphiql-app.shopifycloud.com/login" label="Installed GraphiQL or created an app"> You've either installed the GraphiQL app on your store or [created an app](/docs/apps/build/scaffold-app), with the `read_checkout_branding_settings` and `write_checkout_branding_settings` [access scopes](/docs/api/usage/access-scopes). </Requirement> <Requirement href="/docs/api/admin-graphql" label="You're using API version `2024-04` or higher."> </Requirement> <Requirement href="/docs/apps/checkout/styling" label="You're familiar with the GraphQL Admin API's branding structures."> </Requirement> </Requirements> <StepSection> <Step> <CheckoutQueryPublishedCheckoutProfile area="header" /> </Step> <Step> ### Hide the default back-to-cart icon and buyer journey breadcrumbs Make a request to the `checkoutBrandingUpsert` mutation's [`CheckoutBrandingCustomizationsInput`](/docs/api/admin-graphql/latest/input-objects/CheckoutBrandingCustomizationsInput) object. You'll hide the default back-to-cart icon and the buyer journey breadcrumbs. In a later step, you'll replace these default elements with your own customized breadcrumbs. <Substep> <Codeblock title="POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json"> ```graphql title="GraphQL mutation" mutation updateCheckoutBranding($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId:ID!) { checkoutBrandingUpsert(checkoutBrandingInput:$checkoutBrandingInput, checkoutProfileId:$checkoutProfileId) { checkoutBranding { customizations { buyerJourney { visibility } cartLink { visibility } } } } } ``` ```json title="Query variables" { "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE", "checkoutBrandingInput": { "customizations": { "buyerJourney": { "visibility": "HIDDEN" }, "cartLink": { "visibility": "HIDDEN" } } } } ``` ```json title="JSON response" { "data": { "checkoutBrandingUpsert": { "checkoutBranding": { "customizations": { "buyerJourney": { "visibility": "HIDDEN" }, "cartLink": { "visibility": "HIDDEN" } } } } } } ``` </Codeblock> </Substep> </Step> <Step> ### Create a checkout UI extension To create a checkout UI extension, use Shopify CLI, which generates starter code for building your extension. <Substep> <CheckoutUiCreate /> </Substep> </Step> <Step> ### Set up the target for your extension [Targets](/docs/api/checkout-extensions/checkout#extension-targets) control where your extension renders in the checkout flow. This example uses [purchase.checkout.header.render-after](/docs/api/checkout-ui-extensions/latest/targets/header/purchase-checkout-header-render-after). <Notice type="note"> You'll import and reference <If extension="react">`Extension.jsx`</If><If extension="javascript">`Extension.js`</If>, which you'll create in a [later step](#render-the-custom-breadcrumb). </Notice> <Notice type="note"> There is a corresponding [purchase.thank-you.header.render-after](/docs/api/checkout-ui-extensions/latest/targets/header/purchase-thank-you-header-render-after) target on the **Thank you** page. While this breadcrumbs example only renders in the **Checkout**, other use cases could benefit from targeting both **Checkout** and **Thank you** pages. </Notice> <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/src/Checkout.jsx" tag="custom-header.ext-point" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/src/Checkout.js" tag="custom-header.ext-point" /> #### Export the target from your Checkout script file In your <If extension="react">`Checkout.jsx`</If><If extension="javascript">`Checkout.js`</If> file, set the entrypoint for the checkout extension on the checkout page, and then export it so that you can reference it in your configuration. --- <Resources> [purchase.checkout.header.render-after](/docs/api/checkout-ui-extensions/latest/targets/header/purchase-checkout-header-render-after) </Resources> </Substep> <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/shopify.extension.toml" tag="custom-header.config-ext-point" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/shopify.extension.toml" tag="custom-header.config-ext-point" /> <CheckoutUiReference /> </Substep> </Step> <Step> ## Render the custom breadcrumb In this step you'll populate the header with custom breadcrumb navigation. <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/src/Extension.jsx" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/src/Extension.js" /> #### Create the <If extension="react">Extension.jsx</If><If extension="javascript">Extension.js</If> file Create a new file in your extension's `src` directory named <If extension="react">`Extension.jsx`</If><If extension="javascript">`Extension.js`</If>. This will render the breadcrumbs in the header for the target that you [previously set up](#set-up-the-target-for-your-extension) in <If extension="react">`Checkout.jsx`</If><If extension="javascript">`Checkout.js`</If> </Substep> <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/locales/en.default.json" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/locales/en.default.json" /> #### Add custom translations for strings Add custom translations for your "cart" string. To better support buyers in different locales, you should avoid using hard-coded strings in your extensions. The translated `cart` string is used in line <If extension="react">20 of `Extension.jsx`</If><If extension="javascript">15 of `Extension.js`</If>. --- <Resources> [Localization](/docs/apps/build/checkout/localized-checkout-ui-extensions) </Resources> </Substep> <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/src/Extension.jsx" tag="custom-header.buyer-journey" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/src/Extension.js" tag="custom-header.buyer-journey" /> #### Get the appropriate state to populate your breadcrumbs As the buyer steps through a checkout, their `activeStep` will update to reflect where they are currently in the buyer journey. You may want to provide different treatments for visited `steps`, the `activeStep`, and `steps` in the future. --- <Notice type="note"> `steps` can vary between store setups, such as stores with one-page versus three-page checkout. They can also vary between buyers, such as those purchasing digital-only goods where a "Shipping" step may be omitted. </Notice> <Resources> [useBuyerJourneySteps](/docs/api/checkout-ui-extensions/latest/react-hooks/buyer-journey#useBuyerJourneySteps) [useBuyerJourneyActiveStep](/docs/api/checkout-ui-extensions/latest/react-hooks/buyer-journey#useBuyerJourneyActiveStep) </Resources> </Substep> <Substep> <CodeRef extension="react" href="https://github.com/Shopify/example-checkout--custom-header--react/blob/main/extensions/custom-header/src/Extension.jsx" tag="custom-header.render" /> <CodeRef extension="javascript" href="https://github.com/Shopify/example-checkout--custom-header--js/blob/main/extensions/custom-header/src/Extension.js" tag="custom-header.render" /> #### Add custom breadcrumbs Render custom breadcrumbs using checkout UI components and the `steps` and `activeStep` returned from the buyer journey hooks. --- <Resources> [Divider](/docs/api/checkout-ui-extensions/latest/components/structure/divider) [InlineLayout](/docs/api/checkout-ui-extensions/latest/components/structure/inlinelayout) [Link](/docs/api/checkout-ui-extensions/latest/components/actions/link) [Text](/docs/api/checkout-ui-extensions/latest/components/titles-and-text/text) [View](/docs/api/checkout-ui-extensions/latest/components/structure/view) </Resources> </Substep> </Step> <Step> <CheckoutUiPreview extension="header " /> </Step> <Deploy /> </StepSection> <NextSteps> ## Tutorial complete! Nice work - what you just built could be used by Shopify merchants around the world! Keep the momentum going with these related tutorials and resources. ### Next steps <CardGrid> <LinkCard href="/docs/apps/checkout/localizing-ui-extensions"> #### Localize your extension Learn how to localize the text and number formats in your extension. </LinkCard> <LinkCard href="/docs/api/checkout-ui-extensions/latest/components"> #### Explore the checkout UI extension component reference Learn about all the components you can use in your checkout UI extensions. </LinkCard> <LinkCard href="/docs/apps/checkout/styling"> #### Explore the checkout branding API Learn about other properties that are exposed in the GraphQL Admin API's checkout branding types. </LinkCard> </CardGrid> </NextSteps>