---
title: Customize form controls
description: >-
  Learn how to use the GraphQL Admin API to customize form controls such as
  borders and label positions, button styles, and corner radii. Save your
  changes to either a draft or live checkout.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md
---

ExpandOn this page

* [What you'll learn](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#requirements)
* [Step 1: Retrieve the store's published checkout profile ID](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-1-retrieve-the-stores-published-checkout-profile-id)
* [Step 2: Set the label position and corner radius](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-2-set-the-label-position-and-corner-radius)
* [Step 3: Set the corner radius for checkboxes](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-3-set-the-corner-radius-for-checkboxes)
* [Step 4: Style primary buttons](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-4-style-primary-buttons)
* [Next steps](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#next-steps)

# Customize form controls

Checkout forms consist of different UI components for user input, 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](https://shopify.dev/docs/apps/build/checkout/styling#data-structures) tokens.

You'll learn some sample customizations, but you can use what you've learned to make other form control customizations.

Tip

You can reset styles to their defaults by writing parent fields to `null` with the GraphQL Admin API. Refer to examples of resetting [some](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert#examples-Reset_color_schemes_to_the_defaults) and [all](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert#examples-Reset_all_styling_to_defaults) values to the defaults.

***

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

* The store that you're modifying must be on a [Shopify Plus plan](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plan).
* You've created a new [development store](https://shopify.dev/docs/api/development-stores#create-a-development-store-to-test-your-app) with the [Checkout and Customer Accounts Extensibility](https://shopify.dev/docs/api/developer-previews#checkout-and-customer-accounts-extensibility-developer-preview) feature preview enabled.
* You can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
* You've either [installed the GraphiQL app](https://shopify-graphiql-app.shopifycloud.com/login) on your store or [created an app](https://shopify.dev/docs/apps/build/scaffold-app), with the `read_checkout_branding_settings` and `write_checkout_branding_settings` [access scopes](https://shopify.dev/docs/api/usage/access-scopes).
* You're using API version `2023-10` or higher.
* You're familiar with the [GraphQL Admin API's branding types](https://shopify.dev/docs/apps/build/checkout/styling#data-structures).

***

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

Checkout styling properties apply to a [checkout profile ID](https://shopify.dev/docs/apps/build/checkout/styling#checkout-profile). In this step, you'll retrieve the checkout profile to which you'll apply form control changes.

1. Query [`checkoutProfiles`](https://shopify.dev/docs/api/admin-graphql/latest/queries/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.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query checkoutProfiles {
      checkoutProfiles(first: 1, query: "is_published:true") {
        edges {
          node {
            id
            name
          }
        }
      }
    }
```

## JSON response

```json
{
      "data": {
        "checkoutProfiles": {
          "edges": [
            {
              "node": {
                "id": "gid://shopify/CheckoutProfile/1",
                "name": "Default checkout profile"
              }
            }
          ]
        }
      }
    }
```

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

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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert) mutation's `customizations` object and the [`CheckoutBrandingInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutBrandingInput) input object.

1. Set the label position.

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

   ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

   ## GraphQL mutation

   ```graphql
   mutation CustomizingControls($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
         checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
           checkoutBranding {
             customizations {
               control {
                 labelPosition
               }
             }
           }
           userErrors {
             field
             message
           }
         }
       }
   ```

   ## Query variables

   ```json
   {
         "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
         "checkoutBrandingInput": {
           "customizations": {
             "control": {
               "labelPosition": "OUTSIDE"
             }
           }
         }
       }
   ```

   ## JSON response

   ```json
   {
         "data": {
           "checkoutBrandingUpsert": {
             "checkoutBranding": {
               "customizations": {
                 "control": {
                   "labelPosition": "OUTSIDE"
                 }
               }
             },
             "userErrors": []
           }
         }
       }
   ```

2. Set the corner radius.

   ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

   ## GraphQL mutation

   ```graphql
   mutation CustomizingControls($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
         checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
           checkoutBranding {
             customizations {
               control {
                 cornerRadius
               }
             }
           }
           userErrors {
             field
             message
           }
         }
       }
   ```

   ## Query variables

   ```json
   {
         "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
         "checkoutBrandingInput": {
           "customizations": {
             "control": {
               "cornerRadius": "LARGE"
             }
           }
         }
       }
   ```

   ## JSON response

   ```json
   {
         "data": {
           "checkoutBrandingUpsert": {
             "checkoutBranding": {
               "customizations": {
                 "control": {
                   "cornerRadius": "LARGE"
                 }
               }
             },
             "userErrors": []
           }
         }
       }
   ```

![Form field labels displaying above fields that have a slightly rounded edge](https://shopify.dev/assets/assets/images/apps/checkout/styling/form-controls/label-position-corner-radius-2x-DcIV8W8y.png)

***

## Step 3: Set the corner radius for checkboxes

At this point, checkboxes have the corner radius that [you set for form controls](#step-2-set-the-label-position-and-corner-radius). 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.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation CustomizingControls($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
  checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
    checkoutBranding {
      customizations {
        checkbox {
          cornerRadius
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Query variables

```json
{
  "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
  "checkoutBrandingInput": {
    "customizations": {
      "checkbox": {
        "cornerRadius": "BASE"
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "checkoutBrandingUpsert": {
      "checkoutBranding": {
        "customizations": {
          "checkbox": {
            "cornerRadius": "BASE"
          }
        }
      },
      "userErrors": []
    }
  }
}
```

![The checkbox as a square with slightly rounded edges](https://shopify.dev/assets/assets/images/apps/checkout/styling/form-controls/checkbox-corner-radius-2x-CVElXYK9.png)

***

## 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert) mutation's `customizations` object and the [`CheckoutBrandingInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutBrandingInput) input object.

1. Set the corner radius.

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

   ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

   ## GraphQL mutation

   ```graphql
   mutation CustomizingControls($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
         checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
           checkoutBranding {
             customizations {
               primaryButton {
                 cornerRadius
               }
             }
           }
           userErrors {
             field
             message
           }
       }
   ```

   ## Query variables

   ```json
   {
         "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
         "checkoutBrandingInput": {
           "customizations": {
             "primaryButton": {
               "cornerRadius": "NONE"
             }
           }
         }
       }
   ```

   ## JSON response

   ```json
   {
         "data": {
           "checkoutBrandingUpsert": {
             "checkoutBranding": {
               "customizations": {
                 "primaryButton": {
                   "cornerRadius": "NONE"
                 }
               }
             },
             "userErrors": []
           }
         }
       }
   ```

2. Set the inline padding.

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

   ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

   ## GraphQL mutation

   ```graphql
   mutation CustomizingControls($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
         checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
           checkoutBranding {
             customizations {
               primaryButton {
                 inlinePadding
               }
             }
           }
           userErrors {
             field
             message
           }
         }
       }
   ```

   ## Query variables

   ```json
   {
         "checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
         "checkoutBrandingInput": {
           "customizations": {
             "primaryButton": {
               "inlinePadding": "BASE"
             }
           }
         }
       }
   ```

   ## JSON response

   ```json
   {
         "data": {
           "checkoutBrandingUpsert": {
             "checkoutBranding": {
               "customizations": {
                 "primaryButton": {
                   "inlinePadding": "BASE"
                 }
               }
             },
             "userErrors": []
           }
         }
       }
   ```

![Buttons as rectangles with sharp edges. The button](https://shopify.dev/assets/assets/images/apps/checkout/styling/form-controls/primary-buttons-2x-8sWeYcwK.png)

***

## Next steps

* Explore the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutBrandingUpsert) to learn more about customizing checkout's form controls.

***

* [What you'll learn](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#requirements)
* [Step 1: Retrieve the store's published checkout profile ID](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-1-retrieve-the-stores-published-checkout-profile-id)
* [Step 2: Set the label position and corner radius](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-2-set-the-label-position-and-corner-radius)
* [Step 3: Set the corner radius for checkboxes](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-3-set-the-corner-radius-for-checkboxes)
* [Step 4: Style primary buttons](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#step-4-style-primary-buttons)
* [Next steps](https://shopify.dev/docs/apps/build/checkout/styling/customize-form-controls.md#next-steps)