Build an admin print action UI extension

This guide demonstrates how to build a UI extension for a print action in Shopify admin. This extension lets users print invoices and packing slips directly from order detail pages.

A UI extension for a print action, as displayed in Shopify admin

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Serve a printable document from your app's backend.
Create a UI extension for an admin print action that displays on the order details page.
Create an interface for the extension, allowing merchants to select the documents to print.
Run your 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 read_orders access scope that uses Shopify CLI 3.78 or higher.

You need to explicitly grant the read_orders access scope to your custom app.
You need to request the read_all_orders access scope. You will need this for your extension to work with orders that are more than 60 days old.
You need to request access to protected customer data.
You need to create at least one order in your development store to test the extension. Make sure to mark the order as paid to convert it from a draft order to a fulfilled order.

Project

Extension:

View on GitHub

Anchor to Create a route to serve the printable documentCreate a route to serve the printable document

To begin, you need to create a route in your app that returns the printable documents for an order. You can use JavaScript to customize the document on your app's backend, but the route must return static HTML without any scripts.

Add a new route file at app/routes/print.js. This file contains the route that will serve the printable document.

Remix routes

Use authenticate.admin(request) to authenticate your request and retrieve the cors utility.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Define and handle any routes or URL parameters so you can configure the order and documents to be printed.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

After you've authenticated your app, you can query the GraphQL Admin API to fetch data which you can use to populate the document.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Using the data you've fetched, return the printable document as an HTML response. Be sure to wrap your response in the cors method to automatically set CORS headers. If you need to set CORS headers manually, then set Access-Control-Allow-Origin: "*" after authenticating the request.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Set the title for the printable document using the <title> element. Most browsers will include the document's title by default on the final printed page.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

If your extension will return multiple documents, be sure to create visual breaks in the CSS so each document is printed as a separate page and users know where each document begins.

We recommend using the CSS @media print rule and styles here to ensure that the document prints correctly.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Shopify CLI uses Cloudflare tunnels to serve your app. These tunnels default to obfuscating email addresses in the app.

Wrap the email in a magic comment to ensure that the email address is visible in the document.

Cloudflare email obfuscation

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Anchor to Create an admin print action UI extensionCreate an admin print action UI extension

After you've created a route to serve the printable document, you can create a new UI extension for a print action that displays on the order details page of Shopify admin. The UI extension will use the route you created in the previous step to fetch the documents.

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

Navigate to your app directory:

Terminal
cd <directory>
Run the following command to create a new UI extension for a print action in Shopify admin:

Terminal
shopify app generate extension --template admin_print --flavor react

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

Admin print action structure
extensions/admin-print
├── 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
└── PrintActionExtension.jsx // The code that defines the print action's UI and behavior

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

You can configure the UI extension's interface to allow merchants to select the documents they want to print.

Complete the following steps to create the interface for the UI extension:

Anchor to Review the configurationReview the configuration

The UI extension's static configuration is stored in its .toml file. To ensure that the print action displays on the order details page, validate that the target is set to admin.order-details.print-action.render.

admin.order-details.print-action.render

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

/extensions/admin-print/src/PrintActionExtension.jsx

import { useEffect, useState } from "react";

import {

reactExtension,

useApi,

AdminPrintAction,

BlockStack,

Checkbox,

Text,

} from "@shopify/ui-extensions-react/admin";

// The target used here must match the target used in the extension's toml file (./shopify.extension.toml)

const TARGET = "admin.order-details.print-action.render";

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

function App() {

// The useApi hook provides access to several useful APIs like i18n and data.

const {i18n, data} = useApi(TARGET);

const [src, setSrc] = useState(null);

const [printInvoice, setPrintInvoice] = useState(true);

const [printPackingSlip, setPrintPackingSlip] = useState(false);

useEffect(() => {

const printTypes = []

if (printInvoice) {

printTypes.push("Invoice");

};

if (printPackingSlip) {

printTypes.push("Packing Slip");

};

if (printTypes.length) {

const params = new URLSearchParams({

printType: printTypes.join(','),

orderId: data.selected[0].id

});

const fullSrc = `/print?${params.toString()}`;

setSrc(fullSrc);

} else {

setSrc(null);

}

}, [data.selected, printInvoice, printPackingSlip]);

return (

<Text fontWeight="bold">{i18n.translate('documents')}</Text>

<Checkbox name="Invoice" checked={printInvoice} onChange={(value)=>{setPrintInvoice(value)}}>

Invoice

</Checkbox>

<Checkbox name="Packing Slips" checked={printPackingSlip} onChange={(value)=>{setPrintPackingSlip(value)}}>

Packing Slips

</Checkbox>

</BlockStack>

</AdminPrintAction>

);

}

Anchor to Note the exportNote the export

You can view the source of your extension in the src/PrintActionExtension.jsx file. This file defines a functional React component exported to run at the extension's target. If you ever want to expose the extension at a different target, you need to update the value here and in the .toml file.

Troubleshooting

Anchor to The extension is not renderingThe extension is not rendering

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

/extensions/admin-print/src/PrintActionExtension.jsx

import { useEffect, useState } from "react";

import {

reactExtension,

useApi,

AdminPrintAction,

BlockStack,

Checkbox,

Text,

} from "@shopify/ui-extensions-react/admin";

// The target used here must match the target used in the extension's toml file (./shopify.extension.toml)

const TARGET = "admin.order-details.print-action.render";

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

function App() {

// The useApi hook provides access to several useful APIs like i18n and data.

const {i18n, data} = useApi(TARGET);

const [src, setSrc] = useState(null);

const [printInvoice, setPrintInvoice] = useState(true);

const [printPackingSlip, setPrintPackingSlip] = useState(false);

useEffect(() => {

const printTypes = []

if (printInvoice) {

printTypes.push("Invoice");

};

if (printPackingSlip) {

printTypes.push("Packing Slip");

};

if (printTypes.length) {

const params = new URLSearchParams({

printType: printTypes.join(','),

orderId: data.selected[0].id

});

const fullSrc = `/print?${params.toString()}`;

setSrc(fullSrc);

} else {

setSrc(null);

}

}, [data.selected, printInvoice, printPackingSlip]);

return (

<Text fontWeight="bold">{i18n.translate('documents')}</Text>

<Checkbox name="Invoice" checked={printInvoice} onChange={(value)=>{setPrintInvoice(value)}}>

Invoice

</Checkbox>

<Checkbox name="Packing Slips" checked={printPackingSlip} onChange={(value)=>{setPrintPackingSlip(value)}}>

Packing Slips

</Checkbox>

</BlockStack>

</AdminPrintAction>

);

}

Configure your app's state to set the printable source URL based on the user's inputs. Passing the ID of the current resource to the AdminPrintAction component sets the document to be previewed and printed.

/extensions/admin-print/src/PrintActionExtension.jsx

import { useEffect, useState } from "react";

import {

reactExtension,

useApi,

AdminPrintAction,

BlockStack,

Checkbox,

Text,

} from "@shopify/ui-extensions-react/admin";

// The target used here must match the target used in the extension's toml file (./shopify.extension.toml)

const TARGET = "admin.order-details.print-action.render";

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

function App() {

// The useApi hook provides access to several useful APIs like i18n and data.

const {i18n, data} = useApi(TARGET);

const [src, setSrc] = useState(null);

const [printInvoice, setPrintInvoice] = useState(true);

const [printPackingSlip, setPrintPackingSlip] = useState(false);

useEffect(() => {

const printTypes = []

if (printInvoice) {

printTypes.push("Invoice");

};

if (printPackingSlip) {

printTypes.push("Packing Slip");

};

if (printTypes.length) {

const params = new URLSearchParams({

printType: printTypes.join(','),

orderId: data.selected[0].id

});

const fullSrc = `/print?${params.toString()}`;

setSrc(fullSrc);

} else {

setSrc(null);

}

}, [data.selected, printInvoice, printPackingSlip]);

return (

<Text fontWeight="bold">{i18n.translate('documents')}</Text>

<Checkbox name="Invoice" checked={printInvoice} onChange={(value)=>{setPrintInvoice(value)}}>

Invoice

</Checkbox>

<Checkbox name="Packing Slips" checked={printPackingSlip} onChange={(value)=>{setPrintPackingSlip(value)}}>

Packing Slips

</Checkbox>

</BlockStack>

</AdminPrintAction>

);

}

Anchor to Render a UIRender a UI

To build the interface for your UI extension, return components from src/PrintActionExtension.jsx.

Setting the src prop of the AdminPrintAction container component will display the print preview of the document and enable printing. HTML, PDF, and images are supported.

Tip

If there is no document to print, then pass null to the src prop. You might also want to add an error banner to your extension's UI to indicate to the user why no document is available.

/extensions/admin-print/src/PrintActionExtension.jsx

import { useEffect, useState } from "react";

import {

reactExtension,

useApi,

AdminPrintAction,

BlockStack,

Checkbox,

Text,

} from "@shopify/ui-extensions-react/admin";

// The target used here must match the target used in the extension's toml file (./shopify.extension.toml)

const TARGET = "admin.order-details.print-action.render";

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

function App() {

// The useApi hook provides access to several useful APIs like i18n and data.

const {i18n, data} = useApi(TARGET);

const [src, setSrc] = useState(null);

const [printInvoice, setPrintInvoice] = useState(true);

const [printPackingSlip, setPrintPackingSlip] = useState(false);

useEffect(() => {

const printTypes = []

if (printInvoice) {

printTypes.push("Invoice");

};

if (printPackingSlip) {

printTypes.push("Packing Slip");

};

if (printTypes.length) {

const params = new URLSearchParams({

printType: printTypes.join(','),

orderId: data.selected[0].id

});

const fullSrc = `/print?${params.toString()}`;

setSrc(fullSrc);

} else {

setSrc(null);

}

}, [data.selected, printInvoice, printPackingSlip]);

return (

<Text fontWeight="bold">{i18n.translate('documents')}</Text>

        <Checkbox name="Invoice" checked={printInvoice} onChange={(value)=>{setPrintInvoice(value)}}>

Invoice

</Checkbox>

        <Checkbox name="Packing Slips" checked={printPackingSlip} onChange={(value)=>{setPrintPackingSlip(value)}}>

Packing Slips

</Checkbox>

</BlockStack>

</AdminPrintAction>

);

}

Anchor to Test the extensionTest the extension

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.

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

Navigate to your app directory:

Terminal
cd <directory>
To build and preview your app, either start or restart your server with the following command:

Terminal
shopify app dev
Press p to open the Dev Console.
In the Dev Console, click on the preview link for your print action UI extension.
The order details page opens. If you don't have an order in your store, then you need to create one.

Warning
If you do not have the read_all_orders access scope, ensure that the order you use to test the UI extension is less than 60 days old. Otherwise, your app will fail when fetching the order data.
To launch your UI extension, click the Print dropdown list and select your extension.
Select some options and click Continue to print.
The browser print dialog opens, and you can print the document.

/app/routes/print.js

import { authenticate } from "../shopify.server";

export async function loader({ request }) {

const { cors, admin } = await authenticate.admin(request);

const url = new URL(request.url);

const query = url.searchParams;

const docs = query.get("printType").split(",");

const orderId = query.get("orderId");

const response = await admin.graphql(

`query getOrder($orderId: ID!) {

order(id: $orderId) {

name

createdAt

totalPriceSet {

shopMoney {

amount

}

}`,

{

variables: {

orderId: orderId,

}

);

const orderData = await response.json();

const order = orderData.data.order;

const pages = docs.map((docType) => orderPage(docType, order));

const print = printHTML(pages);

return cors(

new Response(print, {

status: 200,

headers: {

"Content-type": "text/html",

Anchor to Next stepsNext steps

Action and block UI extensions

Complete a tutorial series that describes how to build an UI extension for an issue tracker, using actions and blocks 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?