---
title: Admin UI extensions
description: >
  Admin UI extensions make it possible to surface contextual app functionality
  within the Shopify Admin interface.
api_version: 2023-10
api_name: admin-extensions
source_url:
  html: 'https://shopify.dev/docs/api/admin-extensions/2023-10'
  md: 'https://shopify.dev/docs/api/admin-extensions/2023-10.md'
---

# Admin UI extensions

With admin UI extensions, you can surface app functionality in the Shopify admin.

## Getting started

Use the Shopify CLI to [generate a new extension](https://shopify.dev/apps/tools/cli/commands#generate-extension) within your app.

If you already have a Shopify app, you can skip right to the last command shown here.

![Admin extension example](https://shopify.dev/assets/assets/images/api/admin-extensions/2023-10/action-extension-example-D3UyRVWo.gif)

## Generate an extension

## CLI

```bash
# scaffold an app if you don't already have one:
npm init @shopify/app@latest --name my-app


# navigate to your app's root directory:
cd my-app


# generate a new extension:
npm run generate extension
# follow the steps to create a new
# extension in ./extensions.
```

***

## App authentication

Admin UI extensions can also make authenticated calls to your app's backend. When you use `fetch()` to make a request to your app's configured auth domain or any of its subdomains, an `Authorization` header is automatically added with a Shopify [OpenID Connect ID Token](https://shopify.dev/docs/api/app-bridge-library/reference/id-token). There's no need to manually manage session tokens.

Relative URLs passed to `fetch()` are resolved against your app's `app_url`. This means if your app's backend is on the same domain as your `app_url`, you can make requests to it using `fetch('/path')`.

## Make requests to your app's backend

## Get Product Data

```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';


// Get product info from app backend
async function getProductInfo(id) {
  const res = await fetch(`/api/products/${id}`);
  return res.json();
}


const TARGET = 'admin.product-details.block.render';


export default reactExtension(TARGET, () => <App />);


function App() {
  // Contextual "input" data passed to this extension:
  const {data} = useApi(TARGET);
  const productId = data.selected?.[0]?.id;


  const [productInfo, setProductInfo] = useState();
  useEffect(() => {
    getProductInfo(productId).then(setProductInfo);
  }, [productId]);


  return <Text>Info: {productInfo?.title}</Text>;
}
```

***

## Direct API access

You can make Shopify Admin API requests directly from your extension using the [query API](https://shopify.dev/docs/api/admin-extensions/api/standard-api#standardapi-propertydetail-query) or the standard [web fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)!

Any `fetch()` calls to Shopify's Admin GraphQL API from your extension are automatically authenticated by default. They're fast too, since requests are handled directly by Shopify.

Direct API requests use [Online access](https://shopify.dev/docs/apps/auth/oauth/access-modes#online-access) mode. This means Direct API calls are restricted to the scopes available to the user that's using the extension. If your extension needs to use the offline access mode, you should make requests using your app's backend.

[Developer guide - Learn more about access scopes](https://shopify.dev/docs/api/usage/access-scopes)

## Query Shopify data

##### Fetch Product data

```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';

async function getProduct(id) {
  const res = await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      query: `
        query GetProduct($id: ID!) {
          product(id: $id) {
            title
          }
        }
      `,
      variables: {id},
    }),
  });
  return res.json();
}

const TARGET = 'admin.product-details.block.render';

export default reactExtension(TARGET, () => <App />);

function App() {
  // Contextual "input" data passed to this extension:
  const {data} = useApi(TARGET);

  const [product, setProduct] = useState();
  useEffect(() => {
    const productId = data.selected?.[0]?.id;
    getProduct(productId).then(({data}) => setProduct(data.product));
  }, [data]);

  return <Text strong>The selected product title is {product?.title}</Text>;
}
```

##### Query Product data

```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';

const TARGET = 'admin.product-details.block.render';

export default reactExtension(TARGET, () => <App />);

function App() {
  // Contextual "input" data passed to this extension:
  const {data, query} = useApi(TARGET);

  const [product, setProduct] = useState();
  useEffect(() => {
    const productId = data.selected?.[0]?.id;
    query(
      `query GetProduct($id: ID!) {
          product(id: $id) {
            title
          }
        }
      `,
      {variables: {id: productId}},
    ).then(({data}) => setProduct(data.product));
  }, [data]);

  return <Text strong>The selected product title is {product?.title}</Text>;
}
```

***

## Custom protocols

Custom protocols make it easier to navigate to common locations, and construct URLs.

Shopify Protocol

Use the `shopify:admin` protocol when you want to construct a URL with a root of the Shopify Admin.

App Protocol

Use the `app:` protocol to construct a URL for your app. Shopify will handle constructing the base URL for your app. This works for both embedded and non-embedded apps.

Extension Protocol

Triggers an action extension from a block extension using the `extension:` protocol. The `extensionTarget` is the target of the action extension. The handle is the handle of the action extension that will be opened.

Relative Urls

Relative urls are relative to your app and are useful when you want to link to a route within your app. This works for both embedded and non-embedded apps.

## shopify:admin

##### Link to Product Page

```tsx
<Link to="shopify:admin/products/1234567890" />;
```

##### Fetch data

```ts
fetch('shopify:admin/api/graphql.json', {
  method: 'POST',
  body: JSON.stringify(simpleProductQuery),
});
```

## app:

## Link to Settings

```tsx
<Link to="app:settings/advanced" />;
```

## extension:

## Trigger Action Extension from a Block extension

```tsx
<Link to={`extension:${extension.handle}/${extensionTarget}`} />;
```

## /relative/urls

## Link to route in your app

```tsx
<Link to={`/reviews/${product.id}`} />;
```

***

## Deploying

Use the Shopify CLI to [deploy your app and its extensions](https://shopify.dev/docs/apps/deployment/extension).

## Deploy an extension

## CLI

```bash
# navigate to your app's root directory:
cd my-app


# deploy your app and its extensions:
npm run deploy


# follow the steps to deploy
```

***

## Tutorials and resources

Deepen your understanding of Admin UI extensions with these tutorials and resources.

[Tutorial - Get started building your first admin extension](#getting-started)

[Component APIs - See all available components](https://shopify.dev/docs/api/admin-extensions/components)

[Reference - View a list of available extension targets](https://shopify.dev/docs/api/admin-extensions/api/extension-targets)

[App authentication - Make authenticated requests to your app's backend](#app-authentication)

[Direct API access - Access the Shopify GraphQL API directly](#direct-api-access)

[Custom protocols - Easily construct URLs to navigate to common locations](#custom-protocols)

[UI reference - Figma UI Kit](https://www.figma.com/community/file/1265417558571498993)

***