Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 55 ยท App Extensions

Admin UI Extensions

Extend the Shopify admin with admin action, block, print and link extensions: targets, Polaris web components and calling the GraphQL Admin API from an extension.

Merchants live in the Shopify admin. When your app's feature belongs to a product, an order or a customer, sending them to a separate embedded page is clumsy. Admin UI extensions put your interface exactly where the merchant is already working: a panel on the product page, an item in the "More actions" menu, a printable document on an order.

This lesson covers the four admin extension flavors, how targets work, how you build the interface with Polaris web components, and how an extension talks to the Admin GraphQL API. Extension code needs a real store and the CLI, so it is shown read-only. The runnable parts are stand-ins that mimic the model: a tiny component tree and a fake admin endpoint. Examples target API version 2026-07; regenerate a template with the CLI to see the exact imports your version uses, since the extension tooling evolves between versions.

Four flavors

Flavor What the merchant sees Example target
Admin block A card embedded in a details page admin.product-details.block.render
Admin action An item in the "More actions" menu that opens a modal admin.product-details.action.render
Admin print action An item in the Print menu that produces a document admin.order-details.print-action.render
Admin link A menu item that just navigates, with no UI code declared with a link target in the TOML

A block is always visible and good for status or small forms ("Warranty: 2 years"). An action is on demand and suits a task with a clear finish ("Add to a collection", "Send a quote"). A print action gives the merchant a document to print, such as a packing slip or invoice, built from order data. A link is the cheapest of all: a menu entry that opens your embedded app on a specific page, useful when the job is too big for a modal.

Some targets work on a selection in a list page too, for example an action on selected products in the product index (admin.product-index.selection-action.render).

flowchart LR
  M["Merchant on a product page"] --> B["Block renders inline"]
  M --> A["Opens More actions"]
  A --> AC["Action modal"]
  A --> L["Link to your app page"]
  M --> P["Print menu"]
  P --> PD["Print document"]
  B --> API["Admin GraphQL API"]
  AC --> API

Blocks, actions and print actions all read and write shop data through the same GraphQL API; links hand over to your embedded app.

The TOML

Admin UI extensions are ui_extensions. Each declares a target and the module that renders it.

TOML
# extensions/product-notes/shopify.extension.toml
api_version = "2026-07"

[[extensions]]
name = "Product notes"
handle = "product-notes"
type = "ui_extension"

  [[extensions.targeting]]
  target = "admin.product-details.block.render"
  module = "./src/BlockExtension.jsx"

Merchants only see an extension if your app is installed and the scopes it needs were granted; see Managed Installation and Access Scopes. An extension that writes metafields needs the matching write_products style scope.

Building the interface with Polaris web components

The interface is built from Polaris web components, the s- elements you met in Polaris and App Home Design. In an extension they are rendered by Shopify in its own sandbox, so you use the components rather than arbitrary HTML and CSS. That is what makes your extension look native and keeps the admin fast and safe.

A block, read-only, in the JSX style the CLI templates use:

JSX
// src/BlockExtension.jsx (read-only: needs the Shopify CLI and a store)
import {render} from 'preact';

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

function Extension() {
  // `shopify` is a global that Shopify provides to the extension
  const productId = shopify.data.selected[0].id;

  return (
    <s-admin-block title="Product notes">
      <s-stack direction="block" gap="base">
        <s-text>Editing notes for {productId}</s-text>
        <s-text-area label="Internal note" name="note" />
        <s-button variant="primary">Save note</s-button>
      </s-stack>
    </s-admin-block>
  );
}

Things worth noticing:

  • shopify.data carries the context: for a details page, which resource is shown (selected holds the ids). It replaces props you might expect from React.
  • s-admin-block and s-admin-action are the top-level wrappers for those flavors; the children are ordinary layout and form components.
  • You cannot reach into the admin page, read the DOM outside your root, or inject global CSS. If you need something the components do not offer, the platform probably does not allow it on purpose.

An action looks similar but has buttons in named slots, and closes itself when done:

JSX
// src/ActionExtension.jsx (read-only)
function Extension() {
  const {close, data} = shopify;
  const productId = data.selected[0].id;

  return (
    <s-admin-action heading="Add a note">
      <s-text-area label="Note" name="note" />
      <s-button slot="primary-action" onClick={() => save(productId).then(close)}>
        Save
      </s-button>
      <s-button slot="secondary-actions" onClick={close}>
        Cancel
      </s-button>
    </s-admin-action>
  );
}

The slot names and component props can change between API versions, so treat the snippet as the shape of the idea and copy the current template when you build.

A runnable UI-model stand-in

The real components render inside Shopify. To see the model, this stand-in builds a component tree with an h() helper (what JSX compiles to) and prints it as an outline. It uses the same component names but is not the real renderer.

Node.js Build and print a component tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at how the primary button's disabled flag follows the state: an extension UI is a function from state to a tree, exactly like the React components you may know. Shopify's side turns the tree into real, accessible admin controls.

Calling the Admin GraphQL API

Admin extensions do not need your server to talk to Shopify. From the extension you can fetch a special URL, and Shopify attaches authentication for the current merchant user:

JavaScript
// read-only: runs inside the admin extension sandbox
const response = await fetch('shopify:admin/api/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `#graphql
      mutation SaveNote($metafields: [MetafieldsSetInput!]!) {
        metafieldsSet(metafields: $metafields) {
          metafields { id key }
          userErrors { field message code }
        }
      }`,
    variables: {
      metafields: [{
        ownerId: productId,
        namespace: '$app:notes',
        key: 'internal',
        type: 'single_line_text_field',
        value: note,
      }],
    },
  }),
});
const { data, errors } = await response.json();

This is direct API access. The query runs with your app's granted scopes and the current user's permissions, and the usual rules of Mutations and userErrors apply: top-level errors for malformed or rejected requests, userErrors for validation failures. For anything heavier, such as calling third-party services or storing data in your database, call your own backend with fetch to your app's URL; extensions send a session token that your server verifies like in Session Tokens for Embedded Apps.

A fake admin endpoint

This stand-in recreates the save flow against an in-memory "admin" so you can practice handling both error kinds. The mock accepts only notes up to 80 characters and a known product id; real validation rules are different.

Node.js Save a note and handle errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The extension would show the first result as a toast, the second as a banner inside the modal (keep the modal open so the merchant can fix the text), and the third as a generic failure. Matching the error kind to the message is half of a good extension.

Design rules that save you from review feedback

  • Keep blocks short. They share the page with Shopify's own cards; a tall block pushes important content away.
  • Show loading and empty states. Fetching data takes time; render a placeholder instead of nothing.
  • Make actions finish. Close the modal on success, and say what happened.
  • Request only needed scopes. Merchants see the list at install.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which admin extension flavor suits a task the merchant starts from the More actions menu, finishing in a modal?

    An admin action appears in the actions menu and opens a modal. A block is an always-visible card, and a link only navigates.
  2. 2. Where does the data about the current product reach an admin extension?

    Shopify provides context through the shopify global. selected holds the resource ids for details-page targets.
  3. 3. A metafieldsSet call returns data with a non-empty userErrors array. What should the extension do?

    userErrors are validation failures reported inside a successful response. Show them to the merchant and keep the form open.
  4. 4. Why use Polaris web components instead of arbitrary HTML in an admin extension?

    Extensions run in a sandbox and describe a tree of approved components. Shopify renders them in the admin, which keeps the look and safety consistent.

Summary

  • Admin UI extensions come as blocks, actions, print actions and links, each tied to a target such as admin.product-details.block.render.
  • The interface is a tree of Polaris web components, rendered by Shopify; context arrives through the shopify global.
  • Extensions can call the Admin GraphQL API directly via shopify:admin/api/graphql.json, using your app's scopes and the current user's permissions.
  • Handle top-level errors and userErrors differently, and always show loading, empty and error states.
  • Use a link extension or your embedded app when a job is too large for a modal.

Next: Checkout UI Extensions