Skip to main content

Build an admin action UI extension

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.

The issue tracker action over a modal. The action has input fields for a title and description.

Anchor to What you'll learnWhat 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.

Requirements

Create a Partner account
Create a development store
Scaffold an app

Scaffold an app with the write_products access scope that uses Shopify CLI 3.78 or higher.

  • 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.
  • Add a product to your development store. The product should not have any custom variants at the start of this tutorial.

Project

View on GitHub

Anchor to Create a new UI extensionCreate a new UI extension

Use Shopify CLI to generate starter code for your UI extension.

  1. Navigate to your app directory:

    Terminal

    cd <directory>

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

    Terminal

    shopify app generate extension --template admin_action --name issue-tracker-action --flavor react

    The command creates a new UI extension template in your app's extensions directory with the following structure:

    Admin action structure

    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

Anchor to Create an interface for the UI extensionCreate an interface for the UI extension

To create an interface for the UI extension, complete the following steps:

Anchor to Review the configurationReview 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

Anchor to Update titleUpdate 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. This API gives you access to strings stored in locale files, and automatically chooses the correct string for the current user's locale.

Anchor to Translate titleTranslate title

Optionally translate your title to French.

Anchor to Use components to create the extension's UIUse components to create the extension's UI

Admin UI extensions are rendered using 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

Anchor to Note the exportNote 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.

Caution

The extension point in the component export must match the extension point defined in your .toml file, or the extension won't render.

Anchor to Render a UIRender a UI

To build your action's UX, return some components from src/ActionExtension.jsx.


Tip

At this point, you can use the Dev Console to run your app's server and preview your UI extension. As you preview the UI extension, changes to its code automatically cause it to reload.

Anchor to Write the UI extension's logic and connect to the GraphQL Admin APIWrite 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 through your app's backend. Instead, your UI extension can use direct API access 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
metafieldsSet

Import the getIssues utility method and use it to update the extension state.

Call the updateIssues utility method when the form is submitted.

Anchor to Test the UI extensionTest the UI extension

After you've built the UI extension, test it with the following steps:

  1. Navigate to your app directory:

    Terminal

    cd <directory>

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

    Terminal

    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.

Anchor to Next stepsNext 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.

Was this page helpful?