---
gid: 91696086-8c78-455b-af68-5306f38f4615
title: Build an admin block UI extension
description: Learn how to create UI extensions that display blocks in Shopify admin.
---
{/* TODO */}
{/* */}
{/* */}
This guide is the second part of a five-part tutorial series that describes how to build UI extensions that display as actions and blocks in Shopify admin. Before starting this guide, you'll need to build or copy the admin action UI extension from the [Build a UI extension for an admin action](/docs/apps/build/admin/actions-blocks/build-admin-action) tutorial.
So far, you've created a UI extension for an action that enables buyers to create issues for a product. However, merchants need an easy way to see them. This guide demonstrates how to create a UI extension for a block in Shopify admin that displays buyer-created issues for a product.
## What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Create a UI extension for a block that displays on the product details page.
- Fetch information to populate the UI extension's initial state.
- Connect the UI extension to Shopify admin's contextual save bar, when gathering input, for seamless page editing.
- 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.
Complete or copy the code from the [Build an admin action UI extension](/docs/apps/build/admin/actions-blocks/build-admin-action) tutorial.
## Create an admin block 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 block UI extension:
```bash
shopify app generate extension --template admin_block --name issue-tracker-block --flavor react
```
```bash
POLARIS_UNIFIED=true shopify app generate extension --template admin_block --name issue-tracker-block
```
The command creates a new extension template in your app's `extensions` directory with the following structure:
```text
extensions/issue-tracker-block
├── 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
└── BlockExtension.jsx // The code that defines the block's UI and behavior
```
```text
extensions/issue-tracker-block
├── 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
└── BlockExtension.jsx // The code that defines the block'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, set the target to `admin.product-details.block.render`.
[admin.product-details.block.render](/docs/api/admin-extensions/latest/api/extension-targets#extensiontargets-propertydetail-adminproductdetailsblockrender)
### 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, a UI extension for an admin block uses the [i18n API](/docs/api/admin-extensions/api/block-extension-api#blockextensionapi-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/BlockExtension.jsx` file. This file defines a functional React component that's 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 that's defined in your `.toml` file, or the extension won't render.
You can view the source of your extension in the `src/BlockExtension.jsx` file. This file defines a functional Preact component that's exported to run at the extension's target. 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 block's UX, return some components from `src/BlockExtension.jsx`. You'll create a simple UI to list out your product issues.
## 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. This guide includes a utility file for GraphQL queries.
Your app can also get data from the extension APIs, which includes data on the current resource from the `data` API.
First, you'll need to populate the UI extension's interface with existing issue data. To do this, use direct API calls to query the metafield, and use the metafield data to populate a paginated list in the UI extension's block. Paginate issues to prevent the block from becoming too tall and difficult for users to use.
Create a new file at `./src/utils.js` and add 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 from the `utils.js` file. You'll use it to query the GraphQL Admin API for the initial data for the extension.
### Get initial data and set up pagination
Use the `getIssues` utility method to fetch the initial data for the UI extension. Add a function to manage pagination.
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.
## Update data and integrate with the page's contextual save bar
Next, you'll create a status dropdown and a delete button that enables users to either mark issues as completed or remove them entirely. When you create the status dropdown, you'll integrate it with the page's contextual save bar. This enables users to save changes to your block using the same controls that they would use to save changes to other fields in the Shopify admin.
Import the `updateIssues` utility method and use it to update the UI extension state.
### Handle status changes and deleting issues
Add the functions to handle deleting and changing the status.
Call the `updateIssues` utility method when the issue is deleted and when the form is submitted.
For more information on how to integrate with the contextual save bar, refer to this [reference](/docs/api/admin-extensions/latest#using-forms).
## 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 page, click on the preview link for the issue tracker UI extension. The product details page opens. If you don't have a product in your store, then you need to create one.
5. To find your block, scroll to the bottom of the page. It should display the issues that you've created so far.
6. When you change the status of an issue, the contextual save bar should display. The change is saved when you click the Save button.
### Next steps
#### Connect admin and block UI extensions
In the next tutorial in this series, you'll connect your admin action UI extension to your admin block UI extension, to enable issue editing.
#### Hide UI extensions
Learn how to hide action UI extensions when they're not useful or relevant.
#### Extension targets
Learn about the various places that Shopify admin can display UI extensions.
#### Components
Learn about the full set of available components for writing admin UI extensions.
#### Deploy
Learn how to deploy your UI extensions to merchants.