---
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>