Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 62

Product Customization UI for Merchants

Recommended resources

Hello and welcome back to our capstone project!

In the last lesson, we designed a robust and scalable data model for our Product Customizer App using Metaobjects and Metafields. We decided on a Customizer Option metaobject to define reusable customization types and a product metafield to link these options to specific products.

Today, we transition from data architecture to user experience. Our goal is to build the embedded app UI that merchants will use to define and assign these customization options. Since you have a strong background in React and full-stack development, you'll find the concepts familiar. We'll be using a React-based component library and specific Shopify tools to create a user interface that feels seamlessly integrated into the Shopify Admin.

The Embedded App UI Challenge

Before we dive into code, let's address a "first principles" question. Our app runs inside an <iframe> within the Shopify Admin. How do we make it look and feel like a native part of Shopify, rather than a disconnected webpage?

Shopify provides a two-part solution:

  1. Polaris: This is Shopify's own design system and React component library. By using Polaris components for buttons, forms, and page layouts, our app will automatically match the Shopify Admin's visual language, ensuring consistency, accessibility, and a professional look.
  2. Shopify App Bridge: This is a JavaScript library that creates a communication channel between your app (in the iframe) and the Shopify Admin "chrome" (the main interface outside the iframe). It allows your app to trigger native Shopify UI elements like toast notifications, modals, and, most importantly for us, the ResourcePicker for selecting products.

Using these two tools together is the key to building a high-quality, embedded app experience.

Build Your Own Shopify App - Part 1 (Polaris)

The video 'Build Your Own Shopify App - Part 1 (Polaris)' from Dev With Alex offers a great explanation of why using Polaris is crucial for creating a trustworthy and seamless user experience in an embedded app.

Watch the first 2 minutes and 36 seconds of this video. Focus on the distinction between standalone and embedded apps and the reasons provided for using Polaris in an embedded context.

Designing the Merchant Experience

For our Product Customizer, the merchant needs to perform two main tasks:

  1. Define the library of available customization options (e.g., "Engraving", "Gift Wrapping", "Custom Logo Upload").
  2. Assign specific options from this library to individual products.

We will build a UI with two main sections to accomplish this. The result will be a settings area that looks professional and intuitive, much like this example:

Shopify Embedded App Settings UI Example
This image showcases a settings page built with Polaris components. Note the clean layout with a title, primary action button, and organized cards, which is the standard we will aim for.

Step 1: Building the "Manage Options" Page

First, let's create a central page where merchants can view all the Customizer Option metaobject entries they have created and add new ones.

Our goal is to build a page that:

  • Has a clear title like "Customizer Options".
  • Features a primary button to "Create new option".
  • Displays a list of existing options.

This is a classic Create-Read-Update-Delete (CRUD) interface. We'll use Polaris components like Page, Layout, Card, and ResourceList to build it. The process of creating a new page (or "route") and fetching data for it is a standard pattern in Shopify apps built with frameworks like Remix or Next.js.

Getting Started with Shopify App Bridge - Create a Shopify App

The video 'Getting Started with Shopify App Bridge' provides an excellent, hands-on demonstration of building exactly this type of page. It shows how to create a new route, fetch data from Shopify, and display it in a list.

Watch the sections from 06:54 to 11:32 and 17:20 to 34:19. As you watch, note the following patterns: Creating a new route: See how a new file like app.products.tsx creates a new page in the app. Building the page structure: Pay attention to the use of Page, Layout, and Card components to build the UI skeleton. Fetching data: The video fetches products using GraphQL in a loader function. In our case, we would write a similar GraphQL query to fetch our Customizer Option metaobject entries. The pattern is identical. Displaying data: Observe how the fetched data is passed to a ResourceList component to render a clean, interactive list. We will use this exact component to list our customizer options.

Step 2: The "Create New Option" Form

When a merchant clicks the "Create new option" button, we need to present them with a form. This form will capture the data for a new Customizer Option metaobject entry, based on the schema we designed in the last lesson:

  • label (Single line text)
  • type (A dropdown: "Text", "Dropdown", "File Upload", etc.)
  • price (Money)
  • configuration (JSON)

We'll use Polaris form components to build an intuitive interface.

Advanced Product Customizer Interfaces
This image shows the kind of rich form we are aiming to build. For now, we will focus on creating the basic text and select inputs for the merchant to define these options.

The official Shopify documentation provides a detailed guide on creating a form page, handling its state, and using various Polaris components.

Build a Shopify app using React Router

Shopify's tutorial on building a QR code app is a fantastic resource. We'll use it as a guide to structure our form for creating a new Customizer Option.

Skim through the following sections of this tutorial. You don't need to implement the QR code logic, but focus on the UI patterns and component usage: 'Create a QR code form': Understand the concept of setting up a new route for a form and managing its state with React hooks (useState, useLoaderData). 'Lay out the form': See how s-page, s-section, and s-box (the web component versions of Polaris) are used to structure the page. 'Add a title field': Note the usage of <s-text-field> (or TextField in React) for text input. 'Add destination options': Observe the use of <s-select> (Select in React) for dropdown menus. This is how we'll implement our type field. 'Add save bar': This is a key App Bridge feature. Instead of a simple button, using the ui-save-bar provides a persistent 'Save'/'Discard' bar at the top of the page, which is the standard Shopify pattern.

Test your understanding!

Based on the resources, you want to create a form for a new "Customizer Option". Your form needs a text field for the label and a dropdown for the type. Which Polaris components would you import and use for this?

Show answer

You would import and use Form, FormLayout, TextField, and Select from the @shopify/polaris library. The TextField would be used for the label, and the Select component would be used for the type dropdown.

Step 3: Assigning Options to a Product

This is where App Bridge truly shines. We need a UI where the merchant can first select a product from their store and then pick which Customizer Options should be available for it. Manually building a product search and selection interface would be complex. Instead, we can use App Bridge's ResourcePicker.

The flow will be:

  1. Merchant navigates to an "Assign Options" page in our app.
  2. They click a "Select Product" button.
  3. App Bridge opens a native Shopify modal that allows them to search, filter, and select a product.
  4. Once they confirm, the modal closes, and App Bridge returns the selected product's ID to our app.
  5. Our UI then updates to show the selected product and a list of available Customizer Options with checkboxes, ready for the merchant to make their selection.

This is the most critical piece of integration for our UI.

Build a Shopify app using React Router

Let's return to the official Shopify tutorial, which has a dedicated section for this exact task.

Read the sections 'Add a product selector' and 'Add a way to select the product'. This is extremely important. Focus on: How the App Bridge ResourcePicker is invoked. How the app receives the selected product's data. How the UI is updated to display the chosen product's information.

By using the ResourcePicker, we offload a significant amount of UI complexity to Shopify, ensuring the merchant gets a familiar and powerful selection experience while we can focus on our app's core logic.

Conclusion

In this lesson, we have designed the complete user interface for the merchant-facing side of our capstone project. You've seen how to leverage your existing React skills and combine them with Shopify's specific toolset to build a professional, embedded app.

Key Takeaways:

  • Polaris is the React component library for building UIs that match the Shopify Admin's look and feel.
  • App Bridge is the communication layer that allows your embedded app to interact with the Shopify Admin, enabling features like the ResourcePicker and SaveBar.
  • We've planned a multi-page UI for our app: one page to manage the library of Customizer Options and another to assign those options to specific products.
  • The UI will be built using standard Polaris components like Page, Layout, Card, ResourceList, Form, TextField, and Select.

Next Steps

We now have a complete blueprint for our UI and the data model it will interact with. However, our "Save" buttons are not yet connected to anything. In our next lesson, "Use the Admin API to write the merchant's configuration to product metafields," we will implement the backend logic. You'll write the Node.js and Express.js code to handle the form submissions, make GraphQL API calls to create and update metaobjects, and save the chosen option references to the product's metafield.