import CheckoutUiCreate from 'app/views/partials/apps/checkout/ui-extensions/create.mdx'
import CheckoutUiRequirements from 'app/views/partials/apps/checkout/ui-extensions/requirements.mdx'
import CheckoutUiPreview from 'app/views/partials/apps/checkout/ui-extensions/preview.mdx'
import CheckoutUiReference from 'app/views/partials/apps/checkout/ui-extensions/reference.mdx'
import Deploy from 'app/views/partials/extensions/deploy.mdx'
<Repo extension="react" href="https://github.com/Shopify/example-checkout--read-custom-data--react" />
<Picker name="extension">
<PickerOption name="react" />
</Picker>
<Overview>
Checkout UI extensions can read and display custom data that's stored in [metafields](/docs/apps/build/custom-data/metafields). For example, in this guide you'll learn how to read watering instructions for plants and display that data next to the plant in the order summary at checkout. Learn from an end-to-end example here, and you can use what you've learned to display other types of metafield data at other checkout UI extension targets.
Follow along with this tutorial to build a sample app, or clone the completed sample app.
<Notice type="shopifyPlus" title="Shopify Plus">
Checkout UI extensions are available only to [Shopify Plus](https://www.shopify.com/plus) merchants.
</Notice>
## What you'll learn
In this tutorial, you'll learn how to do the following:
- Add custom data to products using a metafield
- 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
- Render metadata next to products at checkout
- Deploy your extension code to Shopify
</Overview>
<Requirements>
<CheckoutUiRequirements />
</Requirements>
<StepSection>
<Step>
## Create a metafield for a product
In the Shopify admin, define a metafield and add data to it.
<Substep>
### Add a metafield definition
[Add a metafield](https://help.shopify.com/en/manual/custom-data/metafields/metafield-definitions/creating-custom-metafield-definitions) for the product. For this tutorial, set the **Name** and the **Namespace and key** with the following values:
- **Name**: `Watering instructions`
- **Namespace and key**: The namespace is `instructions` and the key is `watering`, entered as `instructions.watering`.
Set the **Type** as **Single line text**.
</Substep>
<Substep>
### Add metafield data
1. Select a product.
1. Under **Product metafields**, in the text field for the metafield definition that you added, enter the data that you want to display in the checkout UI extension. For example, "Average water needed".
1. Click **Save**.
1. Repeat these steps for another product, and add different data. For example, "Very little water needed".
</Substep>
</Step>
<Step>
## Create a checkout UI extension
To create a checkout UI extension, you'll use Shopify CLI, which generates starter code for building your extension.
<Substep>
<CodeRef
extension="react"
href="https://github.com/Shopify/example-checkout--read-custom-data--react/blob/main/extensions/read-custom-data/shopify.extension.toml" />
<CheckoutUiCreate />
</Substep>
</Step>
<Step>
## Set up an extension target
Set up a target for your checkout UI extension. [Targets](/docs/api/checkout-extensions/checkout#extension-targets) control where your extension renders in the checkout flow.
<Substep>
<CodeRef
extension="react"
href="https://github.com/Shopify/example-checkout--read-custom-data--react/blob/main/extensions/read-custom-data/src/Checkout.jsx" tag="read-custom-data.ext-point"/>
### Export the target from your script file
In your <If extension="react">`Checkout.jsx`</If><If extension="javascript">`Checkout.js`</If> file, set the entrypoint for the checkout extension, and then export it so that it can be referenced in your configuration.
Create <If extension="react">a `reactExtension`</If> <If extension="javascript"> an `extension`</If> function that references your target, and export it using the default export.
---
This extension uses the `purchase.checkout.cart-line-item.render-after` target, to display the custom data after the product.
<Resources>
<If extension="react">
[reactExtension](/docs/api/checkout-ui-extensions#extension-targets)
</If>
[purchase.checkout.cart-line-item.render-after](/docs/api/checkout-ui-extensions/latest/targets/order-summary/purchase-checkout-cart-line-item-render-after)
</Resources>
</Substep>
<Substep>
<CodeRef
extension="react"
href="https://github.com/Shopify/example-checkout--read-custom-data--react/blob/main/extensions/read-custom-data/shopify.extension.toml"
tag="read-custom-data.config-ext-point"
/>
<CheckoutUiReference />
</Substep>
</Step>
<Step>
## Reference the metafield in the configuration file
In your checkout UI extension's configuration file, reference the metafield definition so that the extension code in your <If extension="react">`Checkout.jsx`</If><If extension="javascript">`Checkout.js`</If> file can read it.
<Substep>
<CodeRef
extension="react"
href="https://github.com/Shopify/example-checkout--read-custom-data--react/blob/main/extensions/read-custom-data/shopify.extension.toml" tag="read-custom-data.config-metafields"/>
### Add the metafield definition to the extension TOML
Create an `[[extensions.metafields]]` section with the metafield `namespace` and `key`. This needs to match [the metafield definition that you created](#create-a-metafield-for-a-product) in the Shopify admin.
</Substep>
</Step>
<Step>
## Render the extension
Import checkout UI extension resources to render the extension and the metadata in the checkout UI.
<Substep>
<CodeRef
extension="react"
href="https://github.com/Shopify/example-checkout--read-custom-data--react/blob/main/extensions/read-custom-data/src/Checkout.jsx" tag="read-custom-data.imports"
/>
### Import the following checkout UI extension resources to render the extension:
- **`useCartLines`**: Return the current line item for the checkout.
- **`Text`**: Provide semantic value to the text that you're rendering.
- **`useAppMetafields`**: Return the metafield data for the product.
---
<Resources>
[`useCartLines`](/docs/api/checkout-ui-extensions/latest/react-hooks/cart/usecartlines)
[`Text`](/docs/api/checkout-ui-extensions/latest/components/titles-and-text/text)
[`useAppMetafields`](/docs/api/checkout-ui-extensions/latest/apis/metafields#useAppMetafields)
</Resources>
</Substep>
</Step>
<Step>
<CheckoutUiPreview extension="field " />
</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/custom-data/metafields">
#### Learn more about metafields
Learn more about adding and storing additional information about Shopify resources.
</LinkCard>
<LinkCard href="/docs/apps/checkout/best-practices/localizing-ui-extensions">
#### Localize your extension
Learn how to localize 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 the components that you can use in your checkout UI extension.
</LinkCard>
<LinkCard href="/docs/api/checkout-ui-extensions/latest/apis/extensiontargets">
#### Explore the checkout UI extension targets API reference
Learn about the extension targets that are offered in the checkout.
</LinkCard>
</CardGrid>
</NextSteps>