---
title: Build the UI to configure the location rule function
description: Create a UI that merchants can use to configure your location rule function.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/orders-fulfillment/order-routing-apps/location-rules/build-ui
  md: >-
    https://shopify.dev/docs/apps/build/orders-fulfillment/order-routing-apps/location-rules/build-ui.md
api_type: functions
---

# Customize location rule user interface

Merchants add and manage location rules in the Shopify admin. Shopify uses [admin UI extensions](https://shopify.dev/docs/api/admin-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.

**Beta:**

Location rules is a new feature that's only available by request. Reach out to [Shopify Plus Support](https://help.shopify.com/en/support/plus) to know more about your eligibility and the requirements for the beta program.

![Screenshot that shows the merchant UI for configuring the location rule function](https://shopify.dev/assets/assets/images/apps/fulfillments/order-routing-apps/location-rule-merchant-ui-Cp3VjLMQ.png)

***

## 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](https://shopify.dev/docs/api/admin-extensions).

***

## Requirements

* You've completed the [Add configuration to your location rule function](https://shopify.dev/docs/apps/build/orders-fulfillment/order-routing-apps/location-rules/add-configuration) tutorial.
* You created your app with the [React Router app template](https://shopify.dev/docs/api#app-templates).

***

## Step 1: Create the location rule user interface

The following example builds a React-based [admin UI extensions](https://shopify.dev/docs/api/admin-extensions) that enables merchants to create and configure a location rule function.

1. Navigate to your app directory:

   ## Terminal

   ```terminal
   cd <directory>
   ```

2. Run the following command to create a new location rule UI extension:

   ## Terminal

   ```terminal
   shopify app generate extension --template order_routing_location_rule_ui --name location-rule-ui
   ```

3. Choose the language that you want to use. For this tutorial, you should select either **JavaScript** or **TypeScript**.

   ## Terminal

   ```terminal
   ?  What would you like to work in?
   > (1) JavaScript React
     (2) JavaScript
     (3) TypeScript React
     (4) TypeScript
   ```

4. Navigate to `extensions/location-rule-ui`:

   ## Terminal

   ```terminal
   cd extensions/location-rule-ui
   ```

5. Create a new `preferredCountry` state variable:

   ## src/OrderRoutingLocationRule.tsx

   ```tsx
   import { useState } from 'react';


   const defaultValue = data.rule.metafields[0] ? JSON.parse(data.rule.metafields[0].value).countryCode : 'CA';
   const [preferredCountry, setPreferredCountry] = useState(defaultValue);
   ```

6. Update your user interface to provide controls to configure the state variable:

   ## src/OrderRoutingLocationRule.tsx

   ```tsx
   <Form onSubmit={handleSubmit} onReset={handleOnReset}>
     <Box padding="none none base none">
       <Select onChange={setPreferredCountry} value={preferredCountry} label='Select your preferred country' options={[{label:'Canada', value:'CA'}, {label:'United States', value: 'US'}]} />
     </Box>
     <Box padding="base none">
       <Text fontWeight="bold">
         Locations in your preferred county will be prioritized over locations in other countries
       </Text>
     </Box>
   </Form>
   ```

7. Use the `applyMetafieldsChange` API to prepare your changes to be saved to your metafield:

   ## src/OrderRoutingLocationRule.tsx

   ```tsx
   const handleSubmit = () => {
     const value = {
       countryCode: preferredCountry
     };


     const metafieldsChange = [
       {
         namespace: '$app:location-rule',
         key: 'preferred-country',
         type: 'updateMetafield',
         value: JSON.stringify(value),
         valueType: 'json',
       },
     ];


     applyMetafieldsChange(metafieldsChange);
   };
   ```

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

## src/OrderRoutingLocationRule.tsx

```tsx
import { useState } from 'react';


import {
  reactExtension,
  useApi,
  Text,
  Box,
  Form,
  Select,
} 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.settings.order-routing-rule.render';


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


function App() {
  // The useApi hook provides access to several useful APIs like i18n, data and applyMetafieldsChange.
  const {data, applyMetafieldsChange, i18n} = useApi(TARGET);


  const defaultValue = data.rule.metafields[0] ? JSON.parse(data.rule.metafields[0].value).countryCode : 'CA';
  const [preferredCountry, setPreferredCountry] = useState(defaultValue);


  // Transform your state into metafields and send them back to the Shopify admin to batch the
  // changes together with the rest of merchant updates to the routing strategy
  const handleSubmit = () => {
    const value = {
      countryCode: preferredCountry
    };


    const metafieldsChange = [
      {
        namespace: '$app:location-rule',
        key: 'preferred-country',
        type: 'updateMetafield',
        value: JSON.stringify(value),
        valueType: 'json',
      },
    ];


    applyMetafieldsChange(metafieldsChange);
  };


  // Reset your state to the default values
  const handleOnReset = () => {
    console.log('reset');
  };


  return (
    <Form onSubmit={handleSubmit} onReset={handleOnReset}>
      <Box padding="none none base none">
        <Select onChange={setPreferredCountry} value={preferredCountry} label='Select your preferred country' options={[{label:'Canada', value:'CA'}, {label:'United States', value: 'US'}]} />
      </Box>
      <Box padding="base none">
        <Text fontWeight="bold">
          Locations in your preferred county will be prioritized over locations in other countries
        </Text>
      </Box>
    </Form>
  );
}
```

***

## 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.

1. Navigate to your app directory:

   ## Terminal

   ```terminal
   cd <directory>
   ```

2. Navigate to `extensions/location-rule`:

   ## Terminal

   ```terminal
   cd extensions/location-rule
   ```

3. 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.

   ## shopify.extension.toml

   ```toml
   [extensions.ui]
   handle = "location-rule-ui"
   ```

4. Restart your app:

   ## Terminal

   ```terminal
   shopify app dev
   ```

***

## 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](https://help.shopify.com/manual/locations/setting-up-your-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.

1. 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.

2. Select a different prioritized country.

3. Click **Done**.

4. In the context bar, click **Save**.

5. Open your dev store.

6. Add products to your cart, including the one that's stocked in your Canada and US locations.

7. Proceed through checkout.

8. In the Shopify admin, and find your new order. This should be assigned to the location in the country you prioritized.

1) Open your terminal where `shopify app dev` is running, and review your function executions.

   When [testing functions on development stores](https://shopify.dev/docs/apps/build/functions/test-debug-functions#test-your-function-on-a-development-store), 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.

2) In a new terminal window, use the Shopify CLI [`app function replay`](https://shopify.dev/docs/api/shopify-cli/app/app-function-replay) command to [replay a function execution locally](https://shopify.dev/docs/apps/build/functions/test-debug-functions#execute-the-function-locally-using-shopify-cli), and debug your function without the need to re-trigger the function execution on Shopify.

## Terminal

```terminal
shopify app function replay
```

1. Select the function execution from the top of the list. Press `q` to quit when you are finished debugging.

***