Add a field to checkout

A custom field is a property that allows users to enter text into a user interface. For example, you might want to create a custom field that collects delivery instructions from customers.

In this tutorial, you'll use checkout UI extensions to create a custom field for collecting delivery instructions from customers, and then save those instructions to a metafield.

This tutorial is for delivery instructions, but you can use it as an example to build other use cases for custom fields.

Follow along with this tutorial to build a sample app, or clone the completed sample app.

Before you start, consider reviewing our custom field checkout UI extension UX guidelines.

Shopify Plus

Checkout UI extensions are available only to Shopify Plus merchants.

Anchor to What you'll learnWhat you'll learn

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

Generate a checkout UI extension that appears in the checkout flow using Shopify CLI.
Set up configurations for your checkout UI extension in the extension TOML file.
Use the Checkout UI component library to render an optional input field for customers to add a note.
Save the note to a metafield and display the value in the Shopify admin.

Requirements

You've created a Partner account.
You've created a new development store with the following:
- Generated test data
- Checkout and Customer Accounts Extensibility developer preview enabled
You've created an app that uses Shopify CLI 3.0 or higher.

Project

Extension:

View on GitHub

Anchor to Create a checkout UI extensionCreate a checkout UI extension

To create a checkout UI extension, you'll use Shopify CLI, which generates starter code for building your extension.

To create a checkout UI extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

Navigate to your app directory:

Terminal
cd <directory>
Run the following command to create a new checkout UI extension:

Terminal
shopify app generate extension --template checkout_ui --name my-checkout-ui-extension
Select a language for your extension. You can choose from TypeScript, JavaScript, TypeScript React, or JavaScript React.

Tip
TypeScript or JavaScript is suitable for smaller projects that require a more straightforward API. TypeScript React or JavaScript React is suitable when you want an easy model for mapping state updates to UI updates. With JavaScript or TypeScript, you need to map state updates yourself. This process is similar to writing an application targeting the DOM, versus using react-dom.

You should now have a new extension directory in your app's directory. The extension directory includes the extension script at src/index.{file-extension}. The following is an example directory structure:

Checkout UI extension file structure
└── my-app
└── extensions
└── my-checkout-ui-extension
├── src
│ └── Checkout.jsx OR Checkout.js // The index page of the checkout UI extension
├── locales
│ ├── en.default.json // The default locale for the checkout UI extension
│ └── fr.json // The locale file for non-regional French translations
├── shopify.extension.toml // The config file for the checkout UI extension
└── package.json

Start your development server to build and preview your app:

Terminal
shopify app dev

To learn about the processes that are executed when you run dev, refer to the Shopify CLI command reference.
Press p to open the developer console. In the developer console page, click on the preview link for your extension.

Anchor to Set up an extension targetSet up an extension target

Set up a target for your checkout UI extension. Targets control where your extension renders in the checkout flow.

Anchor to Export the extension target from your script fileExport the extension target from your script file

In your Checkout.jsx file, set the entrypoint for the checkout extension, and then export it so it can be referenced in your configuration.

Create a reactExtension function that references your target, and export it using the default export.

This extension uses the purchase.checkout.shipping-option-list.render-after target, so the user can provide all shipping and delivery information at the same stage in the checkout process.

You can define more than one extension target so that merchants can add the extension to multiple locations in checkout. You can do this by using multiple reactExtension functions with different static targets.

reactExtension purchase.checkout.shipping-option-list.render-after

/extensions/custom-field/src/Checkout.jsx

import React, { useState } from "react";

import {

reactExtension,

TextField,

BlockStack,

useApplyMetafieldsChange,

useMetafield,

Checkbox,

} from "@shopify/ui-extensions-react/checkout";

import { useDeliveryGroupListTarget } from "@shopify/ui-extensions-react/checkout";

// Set the entry point for the extension

export default reactExtension("purchase.checkout.shipping-option-list.render-after", () => <App />);

function App() {

// Set up the checkbox state

const [checked, setChecked] = useState(false);

// Define the metafield namespace and key

const metafieldNamespace = "yourAppNamespace";

const metafieldKey = "deliveryInstructions";

// Get a reference to the metafield

const deliveryInstructions = useMetafield({

namespace: metafieldNamespace,

key: metafieldKey,

});

// Set a function to handle updating a metafield

const applyMetafieldsChange = useApplyMetafieldsChange();

// Guard against duplicate rendering of `shipping-option-list.render-after` target for one-time purchase and subscription sections. Calling `applyMetafieldsChange()` on the same namespace-key pair from duplicated extensions would otherwise cause an overwrite of the metafield value.

// Instead of guarding, another approach would be to prefix the metafield key when calling `applyMetafieldsChange()`. The `deliveryGroupList`'s `groupType` could be used to such effect.

const deliveryGroupList = useDeliveryGroupListTarget();

if (!deliveryGroupList || deliveryGroupList.groupType !== 'oneTimePurchase') {

return null;

}

// Set a function to handle the Checkbox component's onChange event

const handleChange = () => {

setChecked(!checked);

};

// Render the extension components

return (

Provide delivery instructions

</Checkbox>

{checked && (

<TextField

label="Delivery instructions"

multiline={3}

onChange={(value) => {

// Apply the change to the metafield

applyMetafieldsChange({

type: "updateMetafield",

namespace: metafieldNamespace,

key: metafieldKey,

valueType: "string",

value,

});

}}

value={deliveryInstructions?.value}

)}

</BlockStack>

);

}

Anchor to Reference the extension targets in your configuration fileReference the extension targets in your configuration file

You can define more than one target so that app users can add the extension to multiple locations in the checkout.

In your checkout UI extension's configuration file, for each of your targets, create an [[extensions.targeting]] section with the following information:

module: The path to the file that contains the extension code.
target: An identifier that specifies where you're injecting code into Shopify. This needs to match the target that you exported from your file/s.

shopify.extension.toml is the configuration file for your extension. It contains basic information and settings.

Note

Whenever you edit your extension configuration file, you need to restart your server for the changes to take effect.

Terminal

shopify app dev

Anchor to Set up a metafieldSet up a metafield

Now that you've set up the extension target, you'll save custom field values in a metafield. Regular metafields are available to any app or extension.

Info

If you need to capture multiple dynamic fields, then consider using checkout attributes where you can define a namespace and key programatically without having to pre-define them in your shopify.extension.toml. For example, you might need to collect input for both one-time purchase and subscription delivery group lists.

Anchor to Define the metafield namespace and keyDefine the metafield namespace and key

Set a namespace and key for the metafield where you want to store the custom field value.

Later, you'll expose values stored in this metafield to merchants in the Shopify admin.

A metafield is a custom field that you can use to store additional information about a Shopify resource. You can use metafields to store information specific to your app without setting up your own storage.

/extensions/custom-field/src/Checkout.jsx

import React, { useState } from "react";

import {

reactExtension,

TextField,

BlockStack,

useApplyMetafieldsChange,

useMetafield,

Checkbox,

} from "@shopify/ui-extensions-react/checkout";

import { useDeliveryGroupListTarget } from "@shopify/ui-extensions-react/checkout";

// Set the entry point for the extension

export default reactExtension("purchase.checkout.shipping-option-list.render-after", () => <App />);

function App() {

// Set up the checkbox state

const [checked, setChecked] = useState(false);

// Define the metafield namespace and key

const metafieldNamespace = "yourAppNamespace";

const metafieldKey = "deliveryInstructions";

// Get a reference to the metafield

const deliveryInstructions = useMetafield({

namespace: metafieldNamespace,

key: metafieldKey,

});

// Set a function to handle updating a metafield

const applyMetafieldsChange = useApplyMetafieldsChange();

// Instead of guarding, another approach would be to prefix the metafield key when calling `applyMetafieldsChange()`. The `deliveryGroupList`'s `groupType` could be used to such effect.

const deliveryGroupList = useDeliveryGroupListTarget();

if (!deliveryGroupList || deliveryGroupList.groupType !== 'oneTimePurchase') {

return null;

}

// Set a function to handle the Checkbox component's onChange event

const handleChange = () => {

setChecked(!checked);

};

// Render the extension components

return (

Provide delivery instructions

</Checkbox>

{checked && (

<TextField

label="Delivery instructions"

multiline={3}

onChange={(value) => {

// Apply the change to the metafield

applyMetafieldsChange({

type: "updateMetafield",

namespace: metafieldNamespace,

key: metafieldKey,

valueType: "string",

value,

});

}}

value={deliveryInstructions?.value}

)}

</BlockStack>

);

}

Anchor to Add a delivery instruction inputAdd a delivery instruction input

Build a basic user interface using components from the checkout UI extensions component library.

Anchor to Add a delivery instruction option and text fieldAdd a delivery instruction option and text field

Using checkout UI components, build a basic UI for the delivery instruction input.

This UI includes a checkbox to specify whether the customer wants to add a delivery instruction. When the checkbox is checked, a text field appears for the customer to enter the delivery instruction. If the customer has already entered a value, then the value is displayed.

Checkout UI extensions are limited to specific UI components exposed by the platform for security reasons. Checkout UI components allow you to create a UI that feels seamless within the checkout experience, and that inherits a merchant's brand settings.

BlockStack Checkbox TextField

/extensions/custom-field/src/Checkout.jsx

import React, { useState } from "react";

import {

reactExtension,

TextField,

BlockStack,

useApplyMetafieldsChange,

useMetafield,

Checkbox,

} from "@shopify/ui-extensions-react/checkout";

import { useDeliveryGroupListTarget } from "@shopify/ui-extensions-react/checkout";

// Set the entry point for the extension

export default reactExtension("purchase.checkout.shipping-option-list.render-after", () => <App />);

function App() {

// Set up the checkbox state

const [checked, setChecked] = useState(false);

// Define the metafield namespace and key

const metafieldNamespace = "yourAppNamespace";

const metafieldKey = "deliveryInstructions";

// Get a reference to the metafield

const deliveryInstructions = useMetafield({

namespace: metafieldNamespace,

key: metafieldKey,

});

// Set a function to handle updating a metafield

const applyMetafieldsChange = useApplyMetafieldsChange();

// Instead of guarding, another approach would be to prefix the metafield key when calling `applyMetafieldsChange()`. The `deliveryGroupList`'s `groupType` could be used to such effect.

const deliveryGroupList = useDeliveryGroupListTarget();

if (!deliveryGroupList || deliveryGroupList.groupType !== 'oneTimePurchase') {

return null;

}

// Set a function to handle the Checkbox component's onChange event

const handleChange = () => {

setChecked(!checked);

};

// Render the extension components

return (

Provide delivery instructions

</Checkbox>

{checked && (

<TextField

label="Delivery instructions"

multiline={3}

onChange={(value) => {

// Apply the change to the metafield

applyMetafieldsChange({

type: "updateMetafield",

namespace: metafieldNamespace,

key: metafieldKey,

valueType: "string",

value,

});

}}

value={deliveryInstructions?.value}

)}

</BlockStack>

);

}

Anchor to Store the user input in the metafieldStore the user input in the metafield

Use the useApplyMetafieldsChange hook to store the value that the customer enters in the metafields property of the checkout. This metafield value is later associated with the order.

useApplyMetafieldsChange is a React hook that lets you write metafield values. To learn more about the hooks available for checkout UI extensions, refer to the Checkout UI extension reference.

useApplyMetafieldsChange

/extensions/custom-field/src/Checkout.jsx

import React, { useState } from "react";

import {

reactExtension,

TextField,

BlockStack,

useApplyMetafieldsChange,

useMetafield,

Checkbox,

} from "@shopify/ui-extensions-react/checkout";

import { useDeliveryGroupListTarget } from "@shopify/ui-extensions-react/checkout";

// Set the entry point for the extension

export default reactExtension("purchase.checkout.shipping-option-list.render-after", () => <App />);

function App() {

// Set up the checkbox state

const [checked, setChecked] = useState(false);

// Define the metafield namespace and key

const metafieldNamespace = "yourAppNamespace";

const metafieldKey = "deliveryInstructions";

// Get a reference to the metafield

const deliveryInstructions = useMetafield({

namespace: metafieldNamespace,

key: metafieldKey,

});

// Set a function to handle updating a metafield

const applyMetafieldsChange = useApplyMetafieldsChange();

// Instead of guarding, another approach would be to prefix the metafield key when calling `applyMetafieldsChange()`. The `deliveryGroupList`'s `groupType` could be used to such effect.

const deliveryGroupList = useDeliveryGroupListTarget();

if (!deliveryGroupList || deliveryGroupList.groupType !== 'oneTimePurchase') {

return null;

}

// Set a function to handle the Checkbox component's onChange event

const handleChange = () => {

setChecked(!checked);

};

// Render the extension components

return (

Provide delivery instructions

</Checkbox>

{checked && (

<TextField

label="Delivery instructions"

multiline={3}

onChange={(value) => {

// Apply the change to the metafield

applyMetafieldsChange({

type: "updateMetafield",

namespace: metafieldNamespace,

key: metafieldKey,

valueType: "string",

value,

});

}}

value={deliveryInstructions?.value}

)}

</BlockStack>

);

}

Anchor to Show the note in the Shopify adminShow the note in the Shopify admin

After you've saved the note metafield to the order, display it on the order details page in the Shopify admin so that users can view it.

Anchor to Add a metafield definition in the Shopify adminAdd a metafield definition in the Shopify admin

In the Shopify admin, add an Order metafield definition for your delivery instruction metafield. The type should be Single line text. Use the same namespace and key that you defined in your Checkout.jsx file.

Tip

If you already placed an order with delivery instructions, then you might need to select the metafield from the Metafields without a definition list.

Anchor to Preview the extensionPreview the extension

Preview your extension to make sure that it works as expected.

Anchor to Start your serverStart your server

Run the Shopify CLI dev command to build your app and preview it on your development store.

Make sure that you select a development store that has enabled the developer preview for Checkout and Customer Accounts Extensibility.

In a terminal, navigate to your app directory.
Either start or restart your server to build and preview your app:

Terminal
shopify app dev
Press p to open the developer console.
In the developer console page, click on the preview link for the custom field extension.

The checkout opens.

Note

Your Provide delivery instructions checkbox should render in the Shipping step of the checkout.

This section describes how to solve some potential errors when you run dev for an app that contains a checkout UI extension.

Anchor to Property token errorProperty token error

If you receive the error ShopifyCLI:AdminAPI requires the property token to be set, then you'll need to use the --checkout-cart-url flag to direct Shopify CLI to open a checkout session for you.

Terminal

shopify app dev --checkout-cart-url cart/{product_variant_id}:{quantity}

Anchor to Missing checkout linkMissing checkout link

If you don't receive the test checkout URL when you run dev, then verify the following:

You have a development store populated with products.
You're logged in to the correct Partners organization and development store. To verify, check your app info using the following command:

Terminal
shopify app info

Otherwise, you can manually create a checkout with the following steps:

From your development store's storefront, add some products to your cart.
From the cart, click Checkout.
From directory of the app that contains your extension, run dev to preview your app:

Terminal
shopify app dev
On the checkout page for your store, change the URL by appending the ?dev=https://{tunnel_url}/extensions query string and reload the page. The tunnel_url parameter allows your app to be accessed using a unique HTTPS URL.

You should now see a rendered order note that corresponds to the code in your project template.

Anchor to Test the extensionTest the extension

Test your extension to make sure that it works as expected.

Anchor to Test the extension in checkoutTest the extension in checkout

Place an order with delivery instructions in the checkout.

With your server running, open the storefront of your development store.
Add a product to the cart and then check out.
Fill out the contact and shipping address information, and then move to the Shipping step of the checkout.

Your Provide delivery instructions checkbox appears.
Select the Provide delivery instructions checkbox. A text field appears.
Enter a value in the text field and then complete the checkout.
In the Shopify admin for the development store, open the order details page for the order that you just placed.

The delivery instructions that you entered are displayed in the Metafields section, in the delivery instructions field that you created.

Delivery instructions in the order details page.

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

Navigate to your app directory.
Run the following command.

Optionally, you can provide a name or message for the version using the --version and --message flags.

Terminal
shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Partner Dashboard.

Anchor to Tutorial complete!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.