Build the UI to configure the location rule function

Merchants add and manage location rules in the Shopify admin. Shopify uses Admin UI extensions to render the location rule editing experience for the merchant. You can customize this UI for your function's configuration needs, or to meet other requirements of your app.

Screenshot that shows the merchant UI for configuring the location rule function

What you'll learn

Anchor link to section titled "What you'll learn"

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

Generate starter code for location rule UI extensions.
Update the location rule user interface with Admin UI extensions.

Requirements

Anchor link to section titled "Requirements"

You've completed the Add configuration to your location rule function tutorial.
You created your app with the Remix app template.

Step 1: Create the location rule user interface

Anchor link to section titled "Step 1: Create the location rule user interface"

The following example builds a React-based Admin UI extensions that enables merchants to create and configure a location rule function.

Navigate to your app directory:
Run the following command to create a new location rule UI extension:
Choose the language that you want to use. For this tutorial, you should select either JavaScript or TypeScript.
Navigate to extensions/location-rule-ui:
Create a new preferredCountry state variable:
Update your user interface to provide controls to configure the state variable:
Use the applyMetafieldsChange API to prepare your changes to be saved to your metafield:

The contents of src/OrderRoutingLocationRule.tsx should look like this:

Step 2: Associate the user interface to the location rule

Anchor link to section titled "Step 2: Associate the user interface to the location rule"

To connect the location rule user interface to a location rule function, set the handle property of the extensions.ui setting in your extension config.

Navigate to your app directory:
Navigate to extensions/location-rule:
Inside of shopify.extension.toml, under the [extensions.ui] heading, add a new key to associate the newly created location rule UI extension with the existing location rule function.
Restart your app:

Step 3: Test the location rule user interface

Anchor link to section titled "Step 3: Test the location rule user interface"

You can test your location rule to ensure it's working as expected, and review logs for your function.

Before you test the location rule, make sure that you have the following:

Two locations in your store in different countries, one of them in Canada and the other one in the US.
One product that is stocked on both locations.

On the Order routing settings page, click the Edit ✎ button next to your rule.

A modal should open showing the custom location rule user interface.
Select a different prioritized country.
Click Done.
In the context bar, click Save.
Open your development store.
Add products to your cart, including the one that's stocked in your Canada and US locations.
Proceed through checkout.
In the Shopify admin, and find your new order. This should be assigned to the location in the country you prioritized.
Open your terminal where shopify app dev is running, and review your function executions.

When testing functions on development stores, the output of dev includes executions of your functions, any debug logging you have added to them, and a link to a local file with the full function execution details.
In a new terminal window, use the Shopify CLI app function replay command to replay a function execution locally, and debug your function without the need to re-trigger the function execution on Shopify.
Select the function execution from the top of the list. Press q to quit when you are finished debugging.
1. Confirm that the function ran using the configured value.