---
title: Build an admin block UI extension
description: Learn how to create UI extensions that display blocks in Shopify admin.
source_url:
  html: https://shopify.dev/docs/apps/build/admin/actions-blocks/build-admin-block
  md: https://shopify.dev/docs/apps/build/admin/actions-blocks/build-admin-block.md
---

# Build an admin block UI extension

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](https://shopify.dev/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.

![The new block UI extension, at the bottom of the page. Two issues, created with the action, display.](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/admin/admin-actions-and-block/build-an-admin-block/block-on-page-csb-BneaXTRv.png)

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

## Requirements

[Create a Partner account](https://www.shopify.com/partners)

[Create a development store](https://shopify.dev/docs/apps/tools/development-stores#create-a-development-store-to-test-your-app)

[Scaffold an app](https://shopify.dev/docs/apps/build/scaffold-app)

Scaffold an app with the `write_products` access scope that uses [Shopify CLI 3.78 or higher](https://shopify.dev/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](https://shopify.dev/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.

[Build an admin action UI extension](https://shopify.dev/docs/apps/admin/admin-actions-and-blocks/build-an-admin-action)

Complete or copy the code from the [Build an admin action UI extension](https://shopify.dev/docs/apps/build/admin/actions-blocks/build-admin-action) tutorial.

## Project

[View on GitHub](https://github.com/Shopify/example-admin-action-and-block-preact)

## Create an admin block UI extension

Use Shopify CLI to [generate starter code](https://shopify.dev/docs/api/shopify-cli/app/app-generate-extension) for your UI extension.

1. Navigate to your app directory:

   ## Terminal

   ```bash
   cd <directory>
   ```

2. Run the following command to create a new admin block UI extension:

   ## Terminal

   ```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:

   ## Admin block 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
     ├── 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](https://shopify.dev/docs/api/admin-extensions/latest/extension-targets?accordionItem=admin-block-locations-product-details#admin-block-locations-product-details)

## /extensions/issue-tracker-block/shopify.extension.toml

```toml
api_version = "2025-10"


[[extensions]]
# Change the merchant-facing name of the extension in locales/en.default.json
name = "t:name"
handle = "issue-tracker-block"
type = "ui_extension"


# Only 1 target can be specified for each Admin block extension
[[extensions.targeting]]
module = "./src/BlockExtension.jsx"
target = "admin.product-details.block.render"
```

### 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](https://shopify.dev/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.

### Note the export

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.

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```

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

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```

## Write the UI extension's logic and connect to the Graph​QL Admin API

After defining the extension's UI, use standard Preact 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](https://shopify.dev/docs/api/admin-graphql) through your app's backend. Instead, your UI extension can use [direct API access](https://shopify.dev/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.

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)

[metafield​Definition​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsSet)

[metafields​Set](https://shopify.dev/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.

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```

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

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```



Tip

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.

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```

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

## /extensions/issue-tracker-block/src/BlockExtension.jsx

```jsx
import { render } from "preact";
import { useEffect, useMemo, useState } from "preact/hooks";


import { updateIssues, getIssues } from "./utils";


export default async () => { {
  render(<Extension />, document.body);
}
const PAGE_SIZE = 3;


function Extension() {
  const { data, i18n } = shopify;


  const [loading, setLoading] = useState(true);
  const [_, setInitialValues] = useState([]);
  const [issues, setIssues] = useState([]);
  const [currentPage, setCurrentPage] = useState(1);


  const productId = data.selected[0].id;
  const issuesCount = issues.length;
  const totalPages = issuesCount / PAGE_SIZE;


  useEffect(() => {
    (async function getProductInfo() {
      // Load the product's metafield of type issues
      const productData = await getIssues(productId);


      setLoading(false);
      if (productData?.data?.product?.metafield?.value) {
        const parsedIssues = JSON.parse(
          productData.data.product.metafield.value,
        );
        setInitialValues(
          parsedIssues.map(({ completed }) => Boolean(completed)),
        );
        setIssues(parsedIssues);
```



Tip

For more information on how to integrate with the contextual save bar, refer to this [reference](https://shopify.dev/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:

   ## Terminal

   ```bash
   cd <directory>
   ```

2. To build and preview your app, either start or restart your server with the following command:

   ## Terminal

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

![The Dev Console, showing both UI extensions.](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/admin/admin-actions-and-block/build-an-admin-block/dev-console-B_T2NZsq.png)

1. When you change the status of an issue, the contextual save bar should display. The change is saved when you click the Save button.

![The new block UI extension, at the bottom of the page. Issues that have been created with the action display.](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/admin/admin-actions-and-block/build-an-admin-block/block-on-page-csb-BneaXTRv.png)

## /extensions/issue-tracker-block/shopify.extension.toml

```toml
api_version = "2025-10"


[[extensions]]
# Change the merchant-facing name of the extension in locales/en.default.json
name = "t:name"
handle = "issue-tracker-block"
type = "ui_extension"


# Only 1 target can be specified for each Admin block extension
[[extensions.targeting]]
module = "./src/BlockExtension.jsx"
target = "admin.product-details.block.render"
```

### Next steps

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/apps/admin/admin-actions-and-blocks/connect-action-and-block)

[Connect admin and block UI extensions](https://shopify.dev/docs/apps/admin/admin-actions-and-blocks/connect-action-and-block)

[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.](https://shopify.dev/docs/apps/admin/admin-actions-and-blocks/connect-action-and-block)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/apps/build/admin/actions-blocks/hide-extensions)

[Hide UI extensions](https://shopify.dev/docs/apps/build/admin/actions-blocks/hide-extensions)

[Learn how to hide action UI extensions when they're not useful or relevant.](https://shopify.dev/docs/apps/build/admin/actions-blocks/hide-extensions)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/admin-extensions/extension-targets)

[Extension targets](https://shopify.dev/docs/api/admin-extensions/extension-targets)

[Learn about the various places that Shopify admin can display UI extensions.](https://shopify.dev/docs/api/admin-extensions/extension-targets)

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/admin-extensions/components)

[Components](https://shopify.dev/docs/api/admin-extensions/components)

[Learn about the full set of available components for writing admin UI extensions.](https://shopify.dev/docs/api/admin-extensions/components)

[![](https://shopify.dev/images/icons/32/build.png)![](https://shopify.dev/images/icons/32/build-dark.png)](https://shopify.dev/docs/apps/deployment/app-versions)

[Deploy](https://shopify.dev/docs/apps/deployment/app-versions)

[Learn how to deploy your UI extensions to merchants.](https://shopify.dev/docs/apps/deployment/app-versions)