---
gid: a31f1697-7808-4d38-927c-f8c545bec25d
title: Build an admin action UI extension
description: Learn how to create UI extensions that display actions in Shopify admin.
---
This guide is the first part of a five-part tutorial series that describes how to build UI extensions that display as actions and blocks in Shopify admin. It demonstrates how to build a UI extension for an action that enables users to log trackable, resolvable issues on products.
## What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Create a UI extension for an action that displays on the product details page in Shopify admin.
- Fetch information to populate the UI extension's initial state.
- Create an interface for the UI extension, allowing it to gather input from merchants.
- Update the data using GraphQL based on merchant input.
- Run the UI extension locally and test it on a development store.
Scaffold an app with the `write_products` access scope that uses [Shopify CLI 3.78 or higher](/docs/api/shopify-cli#upgrade).
- If you created a Remix app, then the `write_products` access scope is automatically granted to your app.
- If you created an extension-only app, then you need to explicitly grant the `write_products` access scope to your [custom app](/docs/apps/auth/access-token-types/admin-app-access-tokens#changing-api-scopes).
- Add a product to your development store. The product should not have any custom variants at the start of this tutorial.
## Create a new UI extension
Use Shopify CLI to [generate starter code](/docs/api/shopify-cli/app/app-generate-extension) for your UI extension.
1. Navigate to your app directory:
```bash
cd
```
2. Run the following command to create a new admin action UI extension:
```bash
shopify app generate extension --template admin_action --name issue-tracker-action --flavor react
```
```bash
POLARIS_UNIFIED=true shopify app generate extension --template admin_action --name issue-tracker-action
```
The command creates a new UI extension template in your app's `extensions` directory with the following structure:
```text
extensions/issue-tracker-action
├── README.md
├── locales
│ ├── en.default.json // The default locale for the extension
│ └── fr.json // The French language translations for the extension
├── package.json
├── shopify.extension.toml // The config file for the extension
└── src
└── AdminAction.jsx // The code that defines the action's UI and behavior
```
```text
extensions/issue-tracker-action
├── README.md
├── locales
│ ├── en.default.json // The default locale for the extension
│ └── fr.json // The French language translations for the extension
├── package.json
├── shopify.extension.toml // The config file for the extension
├── tsconfig.json
├── shopify.d.ts // Provides types for components and APIs available to the extension
└── src
└── AdminAction.jsx // The code that defines the action's UI and behavior
```
## Create an interface for the UI extension
To create an interface for the UI extension, complete the following steps:
### Review the configuration
The UI extension's static configuration is stored in its `.toml` file. To display the issue tracker on product detail pages, validate that the `target` is set to `admin.product-details.action.render`.
[admin.product-details.action.render](/docs/api/admin-extensions/latest/api/extension-targets#extensiontargets-propertydetail-adminproductdetailsactionrender)
### Update title
To update the name that displays when merchants select the action from the menu, edit the `name` value in the locale files. To localize strings, an admin action UI extension uses the [i18n API](/docs/api/admin-extensions/api/action-extension-api#actionextensionapi-propertydetail-i18n). This API gives you access to strings stored in locale files, and automatically chooses the correct string for the current user's locale.
### Translate title
Optionally translate your title to French.
### Use components to create the extension's UI
Admin UI extensions are rendered using [Remote UI](https://github.com/Shopify/remote-dom/tree/remote-ui), which is a fast and secure remote-rendering framework. Because Shopify renders the UI remotely, components used in the extensions must comply with a contract in the Shopify host. We provide these components through the admin UI extensions library.
[Admin UI extensions components](/docs/api/admin-extensions/components)
### Note the export
You can view the source of your extension in the `src/ActionExtension.jsx` file. This file defines a functional React component exported to run at the extension's target. You can create the extension's body by importing and using components from the `@shopify/ui-extensions-react/admin` package.
The extension point in the component export must match the extension point defined in your `.toml` file, or the extension won't render.
You can view the source of your extension in the `src/ActionExtension.jsx` file. This file defines an `extension` function that calls the `render` method from Preact. You can create the extension's body by using the Polaris web components that are automatically provided.
Admin UI extensions are rendered using [Remote DOM](https://github.com/Shopify/remote-dom/tree/remote-dom), which is a fast and secure remote-rendering framework. Because Shopify renders the UI remotely, components used in the extensions must comply with a contract in the Shopify host. We provide these components automatically to the extension.
### Render a UI
To build your action's UX, return some components from `src/ActionExtension.jsx`.
At this point, you can use the Dev Console to [run your app's server and preview your UI extension](#step-4-test-the-extension). As you preview the UI extension, changes to its code automatically cause it to reload.
## Write the UI extension's logic and connect to the GraphQL Admin API
After defining the extension's UI, use standard React tooling to write the logic that controls it.
When you're writing UI extensions, you don't need proxy calls to the [GraphQL Admin API](/docs/api/admin-graphql) through your app's backend. Instead, your UI extension can use [direct API access](/docs/api/admin-extensions#directapiaccess) to create requests directly using `fetch`. For merchants, this makes UI extensions more performant and responsive.
In this step, you'll create a utility file to contain GraphQL queries that the UI extension uses to read and write data to the metafield API.
Your app can also get data from the extension APIs, which includes data on the current resource from the `data` API.
Add new file at `./src/utils.js`. This file contains the GraphQL queries that the extension uses to read and write data to the GraphQL Admin API.
[metafieldDefinitionCreate](/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)
[metafieldsSet](/docs/api/admin-graphql/latest/mutations/metafieldsSet)
Import the `getIssues` utility method and use it to update the extension state.
Call the `updateIssues` utility method when the form is submitted.
## Test the UI extension
After you've built the UI extension, test it with the following steps:
1. Navigate to your app directory:
```bash
cd
```
2. To build and preview your app, either start or restart your server with the following command:
```bash
shopify app dev
```
3. Press `p` to open the Dev Console.
4. In the Dev Console, click on the preview link for the issue tracker extension.
5. The product details page opens. If you don't have a product in your store, then you need to create one.
6. To launch your extension, select it from the **More actions** dropdown found at the top-right of the page.
7. Fill out the modal and click **Create**.
8. Validate that the metafield is created and populated with your issue text, by navigating to the metafields card at the bottom of the page, and select **Show all**.
Update your code to the control the form and write the data to the admin metafield API using the methods from `./src/utils.js`.
### Next steps
#### Admin block UI extension
In the next tutorial in this series, you'll build a UI extension that lists the issues created by your action extension. This new extension will display as a block in Shopify admin.
#### Extension targets
Learn about the various places in Shopify admin where UI extensions can be displayed.
#### Components
Learn about the full set of available components for writing admin UI extensions.