Customize form controls

Checkout forms are made up of different checkout UI components for user inputs, such as Checkbox, DatePicker, and TextField.

This guide teaches you how to use the GraphQL Admin API to customize form controls, beyond what you can customize using the checkout editor. In some cases, you'll style form controls using design system tokens. You'll learn some sample customizations, but you can use what you've learned to make other form control customizations.

What you'll learn

Anchor link to section titled "What you'll learn"

In this tutorial, you’ll learn how to do the following tasks:

Retrieve a list of your store's checkout profile IDs
Customize the label position and corner radius for all form controls
Customize checkboxes to add a distinct corner radius
Customize buttons to add inner padding and a distinct corner radius

Requirements

Anchor link to section titled "Requirements"

The store that you're modifying must be on a Shopify Plus plan.
You've created a new development store with the Checkout and Customer Accounts Extensibility developer preview enabled.
You can make authenticated requests to the GraphQL Admin API.
You've either installed the GraphiQL app on your store or created an app, with the read_checkout_branding_settings and write_checkout_branding_settings access scopes.
You're using API version 2023-10 or higher.
You're familiar with the GraphQL Admin API's branding types.

Step 1: Retrieve the store's published checkout profile ID

Anchor link to section titled "Step 1: Retrieve the store's published checkout profile ID"

Checkout styling properties apply to a checkout profile ID. In this step, you'll retrieve the checkout profile to which you'll apply form control changes.

Query checkoutProfiles to retrieve a list of checkout profile IDs.

The is_published parameter indicates which checkout profile is currently applied to your store's live checkout.
Make note of your corresponding ID from the list. You'll supply the ID in subsequent mutations.

Step 2: Set the label position and corner radius

Anchor link to section titled "Step 2: Set the label position and corner radius"

In this step, you'll set the label position and then the corner radius for form controls. For both styles, you'll use the checkoutBrandingUpsert mutation's customizations object and the CheckoutBrandingInput input object.

Set the label position.

The following example puts labels outside fields. This keeps field labels visible when users are typing inputs, and improves accessibility.
Set the corner radius.

Form field labels displaying above fields that have a slightly rounded edge

Step 3: Set the corner radius for checkboxes

Anchor link to section titled "Step 3: Set the corner radius for checkboxes"

At this point, checkboxes have the corner radius that you set for form controls. However, this style makes the checkboxes look like radio buttons. In this step, you'll adjust the checkbox's corner radius to visually distinguish it as a checkbox and make its function clear.

The checkbox as a square with slightly rounded edges

Step 4: Style primary buttons

Anchor link to section titled "Step 4: Style primary buttons"

The customizations for control don't apply to buttons. In this step, you'll style the corner radius and padding for primary buttons. For both styles, you'll use the checkoutBrandingUpsert mutation's customizations object and the CheckoutBrandingInput input object.

Set the corner radius.

The following example shapes the buttons as rectangles with sharp corners, which affects the perceived clickability of the button.
Set the inline padding.

The following example helps to ensure that the label doesn't touch the button edges, which improves readability and aesthetics.

Next steps

Anchor link to section titled "Next steps"

Explore the GraphQL Admin API to learn more about customizing checkout's form controls.