A customer segment template extension is an extension that is displayed in the template drawer of the customer segment editor.

This guide is the first part in a two-part tutorial series on how to build a feature using customer segment template extensions and an admin action in the **Use segment** modal. This guide demonstrates how to build a customer segment template extension that enables users to create a segment based on a custom query your app provides. The customer segment template extension displays in the template drawer of the customer segment editor under the segment details page.

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/marketing/customer-segments/build-a-customer-segment-template/template-384ef2bb3c7c5671f18581fa9813f8abe8b1b38e952b9500b927ac255b782b8c.png" class="lazyload" alt="An image showing the customer segment template extension." width="3024" height="1654"></figure>

## What you'll learn

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

- Create a customer segment template extension that is displayed in the template drawer of customer segment editor in the Shopify admin.

- Run the extension locally and test it on a development store.

## Requirements

- You've created a [Partner account](https://www.shopify.com/partners) and a [development store](/docs/api/development-stores#create-a-development-store-to-test-your-app).

- You've [created an app that uses the Remix template](/docs/apps/build/scaffold-app).

- Your app is using [Shopify CLI 3.48 or higher](/docs/apps/build/scaffold-app).

    > Tip:
    > [Learn how to check your Shopify CLI version](/docs/api/shopify-cli#upgrade).

## Step 1: Create a new extension

To create your customer segment template extension, you can use Shopify CLI to [generate](/docs/api/shopify-cli/app/app-generate-extension) a starter extension.

1. Navigate to your app directory:

    <p>
    <div class="react-code-block" data-preset="terminal">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>


    <script type="text/plain" data-language="bash">
    RAW_MD_CONTENTcd <directory>
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


1. Run the following command to create a new admin action extension:

    <p>
    <div class="react-code-block" data-preset="terminal">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>


    <script type="text/plain" data-language="bash">
    RAW_MD_CONTENTshopify app generate extension --template customer_segment_template --name loyal-customers-template --flavor react
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


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

    <p>
    <div class="react-code-block" data-preset="file">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>

    <script data-option="filename" data-value="Customer segment template structure"></script>

    <script type="text/plain" data-language="text">
    RAW_MD_CONTENTextensions/loyal-customers-template
    ├── 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
        └── CustomerSegmentTemplate.jsx // The code that defines the action's UI and behavior
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


## Step 2: Build the extension's UI

Complete the following steps to build the extension's UI.

### Review the configuration

The extension's `.toml` file stores the extension's static configuration. To have the template appear in the template drawer of the customer segment editor, validate that the `target` is set to `admin.customers.segmentation-templates.render`. For a full list of targets and the locations where they display in the Shopify admin, refer to the [admin extension configuration](docs/api/admin-extensions/extension-targets) reference.

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="filename" data-value="shopify.extension.toml"></script>

<script type="text/plain" data-language="toml">
RAW_MD_CONTENTapi_version = "2023-10"

[[extensions]]
name = "t:title"
description = "t:description"
handle = "loyal-customers-template"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/CustomerSegmentTemplate.jsx"
# The target must match the target used in the module file (./src/CustomerSegmentTemplate.jsx)
target = "admin.customers.segmentation-templates.render"
END_RAW_MD_CONTENT</script>

</div>
</p>


### Create the UI

> Note:
> This tutorial uses the React implementation of admin UI extensions. If you want to create JavaScript-only extensions, then you'll need to use the [provided API](docs/api/admin-extensions/components) from the root object.

Customer segment template extensions are rendered using [Remote UI](https://github.com/Shopify/remote-dom/tree/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.

> Note:
> Unlike other UI extensions, customer segment template extensions don't support the entire range of [UI components](docs/api/admin-extensions/unstable/components). They're designed to operate in conjunction with the [`CustomerSegmentTemplate`](docs/api/admin-extensions/unstable/components/other/customersegmenttemplate) component.

You can view the source of your extension in the `src/CustomerSegmentTemplate.jsx` file. This file defines a functional React component that's exported to run at the extension's target. The `CustomerSegmentTemplate` component is specifically designed for customer segment template extensions and has already been imported for you. All the template extensions that you create for your application will be displayed under your application's category.

> Caution:
> The extension point in the component export must match the extension point defined in your `.toml` file, or the extension won't render.
>
> If the template refers to a metafield, the metafield needs to exist in our database or the extension won't render.

To build your customer segment template, you need to populate the `CustomerSegmentTemplate` component's `title`, `description`, `query`, `queryToInsert` and `createdOn` props. For a list of all the component's props and their descriptions, refer to the [`CustomerSegmentTemplate` component reference](/docs/api/admin-extensions/components/other/customersegmenttemplate).

Add the following code to `src/CustomerSegmentTemplate.jsx`:

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="filename" data-value="src/CustomerSegmentTemplate.jsx"></script>

<script type="text/plain" data-language="jsx">
RAW_MD_CONTENTimport {
  reactExtension,
  CustomerSegmentTemplate,
  useApi,
} 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.customers.segmentation-templates.render';

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

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

  const query =
    'number_of_orders >= 10';

  return (
    // The CustomerSegmentTemplate component provides an API for setting the title, description, date, query, and query to insert of the segmentation template.
    <CustomerSegmentTemplate
      title={i18n.translate('title')}
      description={i18n.translate('description')}
      createdOn={new Date('2023-10-15').toISOString()}
      query={query}
    />
  );
}
END_RAW_MD_CONTENT</script>

</div>
</p>


> Caution:
> The validity of the query's syntax is not verified and needs to be tested in the customer segment editor.

To update the title and description of the template, edit the corresponding `title` and `description` values in the locale files.

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="filename" data-value="Locales"></script>

<script type="text/plain" data-language="json" data-filename="locales/en.default.json" data-title="English">
RAW_MD_CONTENT{
  "title": "Loyal customers",
  "description": "Use this template to identify your loyal customers, you can reward them with discounts, or award them loyalty points!"
}
END_RAW_MD_CONTENT</script>
<script type="text/plain" data-language="json" data-filename="locales/fr.json" data-title="French">
RAW_MD_CONTENT{
  "title": "Clients fidèles",
  "description": "Utilisez ce modèle pour identifier vos clients fidèles. Vous pouvez les récompenser avec des remises ou leur attribuer des points de fidélité!"
}
END_RAW_MD_CONTENT</script>

</div>
</p>


> Tip:
> You can create queries using your own [metafields](/docs/apps/build/custom-data/metafields). You could choose to query your loyal customers by using a loyalty points metafield. For example, customers that have already 10 loyalty points could be considered as loyal customers. Once the segment is created, an additional number of loyalty points could be awarded to these customers.

## Step 3: Test the extension

After you've built the extension, you can test it by completing the following steps.

1. Navigate to your app directory:

    <p>
    <div class="react-code-block" data-preset="terminal">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>


    <script type="text/plain" data-language="bash">
    RAW_MD_CONTENTcd <directory>
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


1. To build and preview your app, either start or restart your server with the following command:

    <p>
    <div class="react-code-block" data-preset="terminal">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>


    <script type="text/plain" data-language="bash">
    RAW_MD_CONTENTshopify app dev 
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


1. Press `p` to open the developer console. 
1. In the developer console page, click on the preview link for the loyalty points template extension.


    The template drawer of the customer segment editor opens on the customer index page.

    <figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/marketing/customer-segments/build-a-customer-segment-template/dev-console-1b9dc56a9faedf90d09e5a899bd6366b61988d9056a9772fc19cb52273acc9a3.png" class="lazyload" alt="An image showing the developer console with the new customer segment template extension in template drawer of the customer segment editor." width="2248" height="490"></figure>

1. To use your extension, click the **Use this template** button:

    <figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/marketing/customer-segments/build-a-customer-segment-template/template-384ef2bb3c7c5671f18581fa9813f8abe8b1b38e952b9500b927ac255b782b8c.png" class="lazyload" alt="An image showing the customer segment template extension." width="3024" height="1654"></figure>

1. Validate the query inside the customer segment editor:

    <figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/marketing/customer-segments/build-a-customer-segment-template/template-query-in-editor-60ad2d86a409d5a91020bf79bb0cf6fcf2d9ba0c1de39c1f1494b03b5c35d6c9.png" class="lazyload" alt="An image showing the query of the customer segment template extension inside the customer segment editor." width="3020" height="1648"></figure>

## Next steps

- Complete the next guide in this tutorial series by building an [action extension in the **Use segment** modal](/docs/apps/build/marketing-analytics/customer-segments/build-an-action-extension). This will allow your app to use the newly created customer segment.