Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Product Details Configuration API

Requires the AdminBlock component.

The Product Details Configuration API lets you build product configuration extensions for bundles that define product relationships and manage bundle compositions. Use this API to build configuration interfaces for bundle and component product experiences.

Anchor to Use casesUse cases

Bundle configuration: Configure product bundles by defining relationships between bundle and component products.
Component selection: Build interfaces for selecting component products in bundle configurations.
Product relationships: Manage product-to-product relationships for merchandising.
Variant handling: Handle bundle configuration across products with multiple variants.

Support

Targets (1)

Supported targets

admin.product-details.configuration.render

Anchor to PropertiesProperties

The Product Details Configuration API object provides access to product configuration data. Access the following properties on the API object to interact with the current product context, navigate within the admin, and select resources in the admin.product-details.configuration.render target.

Anchor to auth auth required: Provides methods for authenticating calls to your app backend. Use the idToken() method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
Anchor to data data & { product: ; app: { launchUrl: string; applicationUrl: string; }; } required: Product configuration data including the current product, selected items, and app URLs. Use this to access the product being configured and build your configuration interface.
Anchor to extension extension { target: ; } required: The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
Anchor to i18n i18n required: Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
Anchor to intents intents required: Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
Anchor to navigation navigation required: Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (admin.product-details.block.render) to a product details action (admin.product-details.action.render).
Anchor to picker picker required: Opens a custom Picker API dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
Anchor to query query < = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<, "2023-04">; }) => Promise<{ data?: ; errors?: []; }> required: Executes GraphQL queries against the GraphQL Admin API. Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
Anchor to resourcePicker resourcePicker required: Opens the Resource Picker API modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.

Auth

The `Auth` object provides authentication methods for secure communication with your app backend.

idToken
Retrieves a [Shopify OpenID Connect ID token](/docs/api/app-home/apis/id-token) for the current user. Use this token to authenticate requests to your app backend and verify the user's identity. The token is a signed JWT that contains user information and can be validated using Shopify's public keys. Returns `null` if the token can't be retrieved.
```
() => Promise<string>
```

Data

The `Data` object provides access to currently viewed or selected resources in the admin context.

selected
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
{ id: string; }[]
```

Product

A product configuration.

handle
The URL-friendly unique identifier used in product URLs (for example, `'blue-t-shirt'`).
```
string
```
hasOnlyDefaultVariant
Whether the product has only the default variant with no custom options. When `true`, the product has no size, color, or other option variations.
```
boolean
```
id
The product's unique global identifier (GID).
```
string
```
onlineStoreUrl
The URL to view this product on the online store. Use this to create "View in store" links.
```
string
```
options
Product options that define how variants differ (for example, Size, Color, Material). Each option has an ID, name, position, and array of possible values.
```
{ id: string; name: string; position: number; values: string[]; }[]
```
productCategory
The standardized product category taxonomy. Use this for product classification in search and organization.
```
string
```
productComponents
An array of component products that make up this bundle. Each component represents a product included in the bundle configuration.
```
ProductComponent[]
```
productType
The product category or type used for organization (for example, "T-Shirt", "Shoes").
```
string
```
status
The publication status indicating whether the product is active (published), archived (discontinued), or draft (unpublished).
```
'ACTIVE' | 'ARCHIVED' | 'DRAFT'
```
title
The product's display name shown to merchants and customers.
```
string
```
totalInventory
The total available inventory summed across all variants and locations.
```
number
```
totalVariants
The total number of variants this product has.
```
number
```

ProductComponent

A component product that is part of a bundle. Represents an individual product included in a bundle configuration.

componentVariantsCount
The count of variants from this product that are used as bundle components. Use this to understand how many variants are configured in bundles.
```
number
```
featuredImage
The featured image displayed for this component product with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces.
```
{
    id?: string | null;
    url?: string | null;
    altText?: string | null;
  } | null
```
id
The component product's unique global identifier (GID).
```
string
```
nonComponentVariantsCount
The count of variants from this product that aren't used in any bundles. Use this to identify available variants for adding to bundle configurations.
```
number
```
productUrl
The admin URL for this component product. Use this to create links to the product's details page in the admin.
```
string
```
title
The product's display name. Use this to show which product is included in the bundle.
```
string
```
totalVariants
The total number of variants this component product has. Use this to determine if variant selection is needed for this component.
```
number
```

ExtensionTarget

A string literal union of all valid extension target identifiers. Use this type to specify where your Admin UI extension should render, such as `admin.product-details.block.render` for a block on product details pages or `admin.order-details.action.render` for an action on order details pages. The target determines the extension's location, available APIs, and UI components.

keyof ExtensionTargets

ExtensionTargets

admin.abandoned-checkout-details.action.render
An action target that appears in the **More actions** menu on the abandoned checkout details page. Use this to create workflows for cart recovery, customer engagement, or checkout analysis.
```
RenderExtension<
    ActionExtensionApi<'admin.abandoned-checkout-details.action.render'>,
    AllComponents
  >
```
admin.abandoned-checkout-details.action.should-render
A non-rendering target that controls whether the abandoned checkout details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on checkout properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.abandoned-checkout-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.abandoned-checkout-details.block.render
A block target that displays inline content within the abandoned checkout details page. Use this to show cart recovery tools, abandonment analysis, or customer re-engagement options.
```
RenderExtension<
    BlockExtensionApi<'admin.abandoned-checkout-details.block.render'>,
    AllComponents
  >
```
admin.catalog-details.action.render
An action target that appears in the **More actions** menu on the catalog details page. Use this to create workflows for catalog management, market synchronization, or data exports.
```
RenderExtension<
    ActionExtensionApi<'admin.catalog-details.action.render'>,
    AllComponents
  >
```
admin.catalog-details.action.should-render
A non-rendering target that controls whether the catalog details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on catalog properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.catalog-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.catalog-details.block.render
A block target that displays inline content within the catalog details page. Use this to show catalog-specific settings, market information, or synchronization tools.
```
RenderExtension<
    BlockExtensionApi<'admin.catalog-details.block.render'>,
    AllComponents
  >
```
admin.collection-details.action.render
An action target that appears in the **More actions** menu on the collection details page. Use this to create workflows for collection management, product operations, or merchandising tools.
```
RenderExtension<
    ActionExtensionApi<'admin.collection-details.action.render'>,
    AllComponents
  >
```
admin.collection-details.action.should-render
A non-rendering target that controls whether the collection details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on collection properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.collection-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.collection-details.block.render
A block target that displays inline content within the collection details page. Use this to show collection analytics, bulk product operations, or collection-specific tools.
```
RenderExtension<
    BlockExtensionApi<'admin.collection-details.block.render'>,
    AllComponents
  >
```
admin.collection-index.action.render
An action target that appears in the **More actions** menu on the collection index page. Use this to create workflows for collection management, bulk operations, or catalog organization.
```
RenderExtension<
    ActionExtensionApi<'admin.collection-index.action.render'>,
    AllComponents
  >
```
admin.collection-index.action.should-render
A non-rendering target that controls whether the collection index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.collection-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.company-details.action.render
An action target that appears in the **More actions** menu on the company details page. Use this to create workflows for B2B customer management, credit operations, or company data synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.company-details.action.render'>,
    AllComponents
  >
```
admin.company-details.action.should-render
A non-rendering target that controls whether the company details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on company properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.company-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.company-details.block.render
A block target that displays inline content within the company details page. Use this to show B2B customer information, credit limits, or company-specific data.
```
RenderExtension<
    BlockExtensionApi<'admin.company-details.block.render'>,
    AllComponents
  >
```
admin.company-location-details.block.render
A block target that displays inline content within the company location details page. Use this to show location-specific information, shipping preferences, or location management tools.
```
RenderExtension<
    BlockExtensionApi<'admin.company-location-details.block.render'>,
    AllComponents
  >
```
admin.customer-details.action.render
An action target that appears in the **More actions** menu on the customer details page. Use this to create workflows for customer data management, loyalty operations, or CRM integrations.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-details.action.render'>,
    AllComponents
  >
```
admin.customer-details.action.should-render
A non-rendering target that controls whether the customer details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on customer properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-details.block.render
A block target that displays inline content within the customer details page. Use this to show customer-specific information, loyalty data, or custom customer actions.
```
RenderExtension<
    BlockExtensionApi<'admin.customer-details.block.render'>,
    AllComponents
  >
```
admin.customer-index.action.render
An action target that appears in the **More actions** menu on the customer index page. Use this to create workflows for customer management, marketing operations, or bulk data processing.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-index.action.render'>,
    AllComponents
  >
```
admin.customer-index.action.should-render
A non-rendering target that controls whether the customer index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-index.selection-action.render
A selection action target that appears in the **More actions** menu on the customer index page when multiple customers are selected. Use this to create workflows for bulk customer operations, mass email campaigns, or batch data updates.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-index.selection-action.render'>,
    AllComponents
  >
```
admin.customer-index.selection-action.should-render
A non-rendering target that controls whether the customer index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-segment-details.action.render
An action target that appears from the **Use segment** button on the customer segment details page. Use this to create workflows for marketing campaigns, email operations, or segment-based actions.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-segment-details.action.render'>,
    AllComponents
  >
```
admin.customer-segment-details.action.should-render
A non-rendering target that controls whether the customer segment details action appears from the **Use segment** button. Use this to conditionally show or hide your action based on segment properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-segment-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customers.segmentation-templates.render
A render target that provides [customer segment templates](/docs/apps/build/marketing-analytics/customer-segments/build-a-template-extension) in the [customer segment editor](https://help.shopify.com/manual/customers/customer-segmentation/create-customer-segments). Use this target to provide pre-built segment templates that merchants can use as starting points for creating targeted customer groups based on custom criteria.
```
RenderExtension<
    CustomerSegmentTemplateApi<'admin.customers.segmentation-templates.render'>,
    CustomerSegmentTemplateComponent
  >
```
admin.discount-details.action.render
An action target that appears in the **More actions** menu on the discount details page. Use this to create workflows for discount management, promotion analysis, or discount synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.discount-details.action.render'>,
    AllComponents
  >
```
admin.discount-details.action.should-render
A non-rendering target that controls whether the discount details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on discount properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.discount-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.discount-details.function-settings.render
A function settings target that appears when merchants create or edit a discount powered by your discount function, allowing them to configure function-specific settings. Use this to build custom configuration interfaces for discount function parameters.
```
RenderExtension<
    DiscountFunctionSettingsApi<'admin.discount-details.function-settings.render'>,
    AllComponents
  >
```
admin.discount-index.action.render
An action target that appears in the **More actions** menu on the discount index page. Use this to create workflows for discount management, promotional operations, or bulk discount updates.
```
RenderExtension<
    ActionExtensionApi<'admin.discount-index.action.render'>,
    AllComponents
  >
```
admin.discount-index.action.should-render
A non-rendering target that controls whether the discount index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.discount-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-details.action.render
An action target that appears in the **More actions** menu on the draft order details page. Use this to create workflows for draft order processing, custom pricing, or order preparation tools.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-details.action.render'>,
    AllComponents
  >
```
admin.draft-order-details.action.should-render
A non-rendering target that controls whether the draft order details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on draft order properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-details.block.render
A block target that displays inline content within the draft order details page. Use this to show custom pricing calculations, special order handling tools, or order-specific information.
```
RenderExtension<
    BlockExtensionApi<'admin.draft-order-details.block.render'>,
    AllComponents
  >
```
admin.draft-order-index.action.render
An action target that appears in the **More actions** menu on the draft order index page. Use this to create workflows for draft order management, bulk operations, or order conversion tools.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-index.action.render'>,
    AllComponents
  >
```
admin.draft-order-index.action.should-render
A non-rendering target that controls whether the draft order index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-index.selection-action.render
A selection action target that appears in the **More actions** menu on the draft order index page when multiple draft orders are selected. Use this to create workflows for bulk draft order operations, batch conversions, or mass order processing.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-index.selection-action.render'>,
    AllComponents
  >
```
admin.draft-order-index.selection-action.should-render
A non-rendering target that controls whether the draft order index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.gift-card-details.action.render
An action target that appears in the **More actions** menu on the gift card details page. Use this to create workflows for gift card processing, balance adjustments, or custom gift card operations.
```
RenderExtension<
    ActionExtensionApi<'admin.gift-card-details.action.render'>,
    AllComponents
  >
```
admin.gift-card-details.action.should-render
A non-rendering target that controls whether the gift card details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on gift card properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.gift-card-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.gift-card-details.block.render
A block target that displays inline content within the gift card details page. Use this to show gift card balance tracking, usage history, or custom gift card metadata.
```
RenderExtension<
    BlockExtensionApi<'admin.gift-card-details.block.render'>,
    AllComponents
  >
```
admin.order-details.action.render
An action target that appears in the **More actions** menu on the order details page. Use this to create workflows for order processing, fulfillment operations, or external system integrations.
```
RenderExtension<
    ActionExtensionApi<'admin.order-details.action.render'>,
    AllComponents
  >
```
admin.order-details.action.should-render
A non-rendering target that controls whether the order details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on order properties, fulfillment status, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-details.block.render
A block target that displays inline content within the order details page. Use this to show order-specific information, fulfillment tools, or custom order actions.
```
RenderExtension<
    BlockExtensionApi<'admin.order-details.block.render'>,
    AllComponents
  >
```
admin.order-details.print-action.render
A print action target that appears in the **Print** menu on the order details page. Use this to generate custom documents such as packing slips, shipping labels, or invoices.
```
RenderExtension<
    PrintActionExtensionApi<'admin.order-details.print-action.render'>,
    AllComponents
  >
```
admin.order-details.print-action.should-render
A non-rendering target that controls whether the order details print action appears in the **Print** menu. Use this to conditionally show or hide your print action based on order properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-details.print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-fulfilled-card.action.render
An action target that appears in the actions menu inside the order fulfilled card, visible only on orders fulfilled by your app. Use this to create workflows for fulfillment operations, tracking updates, or post-fulfillment actions.
```
RenderExtension<
    ActionExtensionApi<'admin.order-fulfilled-card.action.render'>,
    AllComponents
  >
```
admin.order-fulfilled-card.action.should-render
A non-rendering target that controls whether the order fulfilled card action appears in the actions menu. Use this to conditionally show or hide your action based on fulfillment properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-fulfilled-card.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.action.render
An action target that appears in the **More actions** menu on the order index page. Use this to create workflows for order management, reporting, or fulfillment operations.
```
RenderExtension<
    ActionExtensionApi<'admin.order-index.action.render'>,
    AllComponents
  >
```
admin.order-index.action.should-render
A non-rendering target that controls whether the order index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.selection-action.render
A selection action target that appears in the **More actions** menu on the order index page when multiple orders are selected. Use this to create workflows for bulk order operations, batch fulfillment, or mass order processing.
```
RenderExtension<
    ActionExtensionApi<'admin.order-index.selection-action.render'>,
    AllComponents
  >
```
admin.order-index.selection-action.should-render
A non-rendering target that controls whether the order index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.selection-print-action.render
A print action target that appears in the **Print** menu on the order index page when multiple orders are selected. Use this to generate batch documents such as combined packing slips, shipping manifests, or bulk invoices.
```
RenderExtension<
    PrintActionExtensionApi<'admin.order-index.selection-print-action.render'>,
    AllComponents
  >
```
admin.order-index.selection-print-action.should-render
A non-rendering target that controls whether the order index selection print action appears in the **Print** menu. Use this to conditionally show or hide your bulk print action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.selection-print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.action.render
An action target that appears in the **More actions** menu on the product details page. Use this to create workflows for processing products, syncing data, or integrating with external systems.
```
RenderExtension<
    ActionExtensionApi<'admin.product-details.action.render'>,
    AllComponents
  >
```
admin.product-details.action.should-render
A non-rendering target that controls whether the product details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on product properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.block.render
A block target that displays inline content within the product details page. Use this to show product-specific information, tools, or actions directly on the product page.
```
RenderExtension<
    BlockExtensionApi<'admin.product-details.block.render'>,
    AllComponents
  >
```
admin.product-details.configuration.render
A configuration target that renders product configuration settings for [product bundles](/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui) and customizable products on the product details page. Use this to define bundle component selections, customization options, or product configuration rules.
```
RenderExtension<
    ProductDetailsConfigurationApi<'admin.product-details.configuration.render'>,
    AllComponents
  >
```
admin.product-details.print-action.render
A print action target that appears in the **Print** menu on the product details page. Use this to generate custom documents such as product labels, barcode sheets, or specification sheets.
```
RenderExtension<
    PrintActionExtensionApi<'admin.product-details.print-action.render'>,
    AllComponents
  >
```
admin.product-details.print-action.should-render
A non-rendering target that controls whether the product details print action appears in the **Print** menu. Use this to conditionally show or hide your print action based on product properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-details.print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.reorder.render
A block target that provides custom reordering functionality on the product details page. Use this to help merchants rearrange product data.
```
RenderExtension<
    BlockExtensionApi<'admin.product-details.reorder.render'>,
    AllComponents
  >
```
admin.product-index.action.render
An action target that appears in the **More actions** menu on the product index page. Use this to create workflows for product management, catalog operations, or inventory synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.product-index.action.render'>,
    AllComponents
  >
```
admin.product-index.action.should-render
A non-rendering target that controls whether the product index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-index.selection-action.render
A selection action target that appears in the **More actions** menu on the product index page when multiple products are selected. Use this to create workflows for bulk product operations, batch updates, or mass data processing.
```
RenderExtension<
    ActionExtensionApi<'admin.product-index.selection-action.render'>,
    AllComponents
  >
```
admin.product-index.selection-action.should-render
A non-rendering target that controls whether the product index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-index.selection-print-action.render
A print action target that appears in the **Print** menu on the product index page when multiple products are selected. Use this to generate batch documents such as combined product labels, barcode sheets, or catalog pages.
```
RenderExtension<
    PrintActionExtensionApi<'admin.product-index.selection-print-action.render'>,
    AllComponents
  >
```
admin.product-index.selection-print-action.should-render
A non-rendering target that controls whether the product index selection print action appears in the **Print** menu. Use this to conditionally show or hide your bulk print action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.selection-print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-purchase-option.action.render
An action target that appears in the **Purchase Options** card on the product details page when a selling plan group is present. Use this to create workflows for subscription management, selling plan configuration, or purchase option operations.
```
RenderExtension<
    PurchaseOptionsCardConfigurationApi<'admin.product-purchase-option.action.render'>,
    AllComponents
  >
```
admin.product-variant-details.action.render
An action target that appears in the **More actions** menu on the product variant details page. Use this to create workflows for variant management, inventory operations, or data synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.product-variant-details.action.render'>,
    AllComponents
  >
```
admin.product-variant-details.action.should-render
A non-rendering target that controls whether the product variant details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on variant properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-variant-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-variant-details.block.render
A block target that displays inline content within the product variant details page. Use this to show variant-specific data, inventory tools, or variant configuration options.
```
RenderExtension<
    BlockExtensionApi<'admin.product-variant-details.block.render'>,
    AllComponents
  >
```
admin.product-variant-details.configuration.render
A configuration target that renders product variant configuration settings for [product bundles](/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui) and customizable products on the product variant details page. Use this to define variant-specific bundle components, customization options, or configuration rules.
```
RenderExtension<
    ProductVariantDetailsConfigurationApi<'admin.product-variant-details.configuration.render'>,
    AllComponents
  >
```
admin.product-variant-purchase-option.action.render
An action target that appears in the **Purchase Options** card on the product variant details page when a selling plan group is present. Use this to create workflows for variant-specific subscription management, selling plan configuration, or purchase option operations.
```
RenderExtension<
    PurchaseOptionsCardConfigurationApi<'admin.product-variant-purchase-option.action.render'>,
    AllComponents
  >
```
admin.settings.internal-order-routing-rule.render
A function settings target that renders within order routing settings, allowing merchants to configure order routing rule functions.
```
RenderExtension<
    OrderRoutingRuleApi<'admin.settings.internal-order-routing-rule.render'>,
    AllComponents | OrderRoutingComponents
  >
```
admin.settings.order-routing-rule.render
A function settings target that renders within order routing settings, allowing merchants to configure order routing rule functions. Use this to build custom configuration interfaces for order routing function parameters.
```
RenderExtension<
    OrderRoutingRuleApi<'admin.settings.order-routing-rule.render'>,
    AllComponents
  >
```
admin.settings.validation.render
A function settings target that renders within a validation's add and edit views, allowing merchants to configure validation function settings. Use this to build custom configuration interfaces for validation function parameters and rules.
```
RenderExtension<
    ValidationSettingsApi<'admin.settings.validation.render'>,
    AllComponents
  >
```

Playground

RenderExtension<StandardApi<'Playground'>, AllComponents>

RenderExtension

Defines a render extension that displays UI in the Shopify admin. Your extension receives a connection object with UI components and an API object with extension capabilities. Use this to build extensions that render visual interfaces in various admin contexts.

ActionExtensionApi

The `ActionExtensionApi` object provides methods for action extensions that render in modal overlays. Access the following properties on the `ActionExtensionApi` object to interact with the current context, control the modal, and display picker dialogs.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
close
Closes the extension modal. Use this when your extension completes its task or the merchant wants to exit. Equivalent to clicking the close button in the overlay corner.
```
() => void
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

I18n

Internationalization utilities for formatting and translating content according to the user's locale. Use these methods to display numbers, currency, dates, and translated strings that match the merchant's language and regional preferences.

formatCurrency
Returns a localized currency value formatted according to the user's locale and currency conventions. Use this to display prices, totals, or financial amounts in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. Uses the current user's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
formatDate
Returns a localized date value formatted according to the user's locale and date conventions. Use this to display dates and times in the appropriate format for the merchant's region, such as order dates, timestamps, or schedule information. This function behaves like the standard `Intl.DateTimeFormat()` and uses the current user's locale by default. Formatting options can be passed to customize the date display style.
```
(date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string
```
formatNumber
Returns a localized number formatted according to the user's locale. Use this to display numbers like quantities, percentages, or measurements in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `decimal` applied. Uses the current user's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
translate
Returns translated content in the user's locale, as supported by the extension. Use this to display localized strings from your extension's locale files. The special `options.count` property enables pluralization. Other option keys and values are treated as replacements for interpolation in your translation strings. Returns a single string when replacements are primitives, or an array when replacements contain UI components.
```
I18nTranslate
```

I18nTranslate

The translation function signature for internationalization. Use this to translate string keys defined in your locale files into localized content for the current user's language.

Intents

Information provided to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.

launchUrl
The URL that was used to launch the intent. Use this to understand how your extension was invoked or to pass context between extensions.
```
string | URL
```

PickerApi

The `picker` function opens a custom selection dialog with your app-specific data. It accepts configuration options to define the picker's heading, items, headers, and selection behavior. It returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.

options
```
PickerOptions
```

returns

Promise<Picker>

PickerOptions

The configuration options for the custom picker dialog. Define the picker's appearance, selection behavior, and data structure.

headers
The column headers for the picker table. Define headers to label and organize the data columns displayed for each item. The header order determines the column layout.
```
Header[]
```
heading
The heading displayed at the top of the picker modal. Use a clear, descriptive title that tells merchants what they're selecting.
```
string
```
items
The list of items that merchants can select from. Each item appears as a row in the picker table.
```
Item[]
```
multiple
The selection mode for the picker. Pass `true` to allow unlimited selections, `false` for single-item selection only, or a number to set a maximum selection limit (for example, `3` allows up to three items).
```
boolean | number
```

Header

The configuration for a table column header in the picker. Each header creates a labeled column that displays corresponding data from items.

content
The label text displayed at the top of the table column. Use clear, concise labels that describe the data in that column (for example, "Price", "Status", "Last Updated").
```
string
```
type
The data type that controls column formatting and text alignment. Use `'number'` for currency, prices, or numeric values (displays right-aligned), or `'string'` for text content (displays left-aligned).
```
'string' | 'number'
```

Item

An individual item that merchants can select in the picker. Each item appears as a row in the picker table.

badges
Status or context badges displayed next to the heading in the first column. Use badges to highlight item state, completion status, or other important attributes (for example, "Draft", "Published", "Incomplete").
```
Badge[]
```
data
Additional data displayed in subsequent columns after the heading. Each value appears in its own column, and the order must match the `headers` array. For example, if headers are `["Price", "Status"]`, then data would be `[19.99, "Active"]`.
```
DataPoint[]
```
disabled
Whether the item can be selected. When `true`, the item is disabled and can't be selected. Disabled items appear grayed out and merchants can't choose them. Use this for items that are unavailable or don't meet selection criteria.
```
boolean
```
heading
The primary text displayed in the first column. This is typically the item's name or title and is the most prominent text in the row.
```
string
```
id
The unique identifier for this item. This ID is returned in the selection array when the merchant selects this item. Use an ID that helps you identify the item in your system (for example, template IDs, review IDs, or custom option keys).
```
string
```
selected
Whether the item is preselected when the picker opens. When `true`, the item appears selected by default. Merchants can still deselect preselected items. Use this to show current selections or suggest default choices.
```
boolean
```
thumbnail
A small preview image or icon displayed at the start of the row. Thumbnails help merchants visually identify items at a glance. Provide a URL to the image file.
```
{ url: string; }
```

Badge

A badge displayed next to an item in the picker to show status or progress. Use badges to highlight important item attributes or states that affect selection decisions.

content
The text content of the badge. Keep this short and descriptive (for example, "Draft", "Active", "Incomplete").
```
string
```
progress
The progress indicator for the badge. Use this to show completion status for items that have progress states.
```
Progress
```
tone
The visual tone indicating status or importance. Choose a tone that matches the badge's meaning.
```
Tone
```

Progress

The progress state for picker badges showing completion status. Use this to indicate how complete an item is: `'incomplete'` for not started, `'partiallyComplete'` for in progress, or `'complete'` for finished.

'incomplete' | 'partiallyComplete' | 'complete'

Tone

The tone communicates the intent or status of a message to the user. - `info`: Neutral informational content with no implied urgency. - `success`: Indicates a successful action or a positive state. - `warning`: Indicates something that requires the user's attention but isn't blocking. - `critical`: Indicates a serious problem or error that needs immediate action.

'info' | 'success' | 'warning' | 'critical'

DataPoint

A single data point that can appear in a picker table cell. Can be text, a number, or undefined if the cell should be empty.

string | number | undefined

Picker

A handle returned when opening a picker dialog. Use this to access the merchant's selection after they confirm or cancel the picker.

selected
A Promise that resolves with an array of selected item IDs when the merchant presses the **Select** button, or `undefined` if they cancel. Await this Promise to handle the selection result.
```
Promise<string[] | undefined>
```

ApiVersion

The supported GraphQL Admin API versions. Use this to specify which API version your GraphQL queries should execute against. Each version includes specific features, bug fixes, and breaking changes. The `unstable` version provides access to the latest features, and can change without notice because it's not subject to versioning guarantees.

'2023-04' | '2023-07' | '2023-10' | '2024-01' | '2024-04' | '2024-07' | '2024-10' | '2025-01' | '2025-04' | 'unstable'

GraphQLError

The GraphQL error returned by the [GraphQL Admin API](/docs/api/admin-graphql).

locations
The location in the GraphQL query where the error occurred. Provides the line number and column position to help identify the exact source of the error in your query string.
```
{ line: number; column: string; }
```
message
A human-readable error message describing what went wrong with the GraphQL query. Use this to understand the cause of the error and how to fix your query.
```
string
```

ResourcePickerApi

Opens the resource picker modal for selecting products, variants, or collections. Returns a Promise that resolves to the selected resources when the merchant confirms, or `undefined` if they cancel. The returned selection includes full resource data with properties like title, price, images, and IDs.

options
```
ResourcePickerOptions
```

returns

Promise<SelectPayload<ResourcePickerOptions['type']> | undefined>

ResourcePickerOptions

The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. Access the following properties on the `ResourcePickerOptions` object to configure the resource picker's appearance and functionality.

action
The action verb that appears in the picker's title and primary button. Use `'add'` for actions that add new items (for example, "Add products") or `'select'` for choosing existing items (for example, "Select products"). This helps merchants understand the picker's purpose.
```
'add' | 'select'
```
filter
Filtering options that control which resources appear in the picker. Use filters to restrict resources by publication status, include or exclude variants, or apply custom search criteria. This helps merchants find relevant items faster.
```
Filters
```
multiple
The selection mode for the picker. Pass `true` to allow unlimited selections, `false` for single-item selection only, or a number to set a maximum selection limit (for example, `5` allows up to five items). When `type` is `'product'`, merchants can still select multiple variants from a single product even if `multiple` is `false`.
```
boolean | number
```
query
An initial search query that appears in the picker's search bar when it opens. Merchants can see and edit this query. See [search syntax](/docs/api/usage/search-syntax) for the query format. For most use cases, use `filter.query` instead, which filters results without exposing the query to merchants.
```
string
```
selectionIds
Resources that should be preselected when the picker opens. Pass an array of resource objects with IDs (and optional variant IDs) to show which items are already selected. Merchants can deselect these preselected items. Use this to show current selections or default choices.
```
BaseResource[]
```
type
The type of Shopify resource to select: `'product'` for products, `'variant'` for specific product variants, or `'collection'` for collections. This determines what appears in the picker and what data structure is returned.
```
'product' | 'variant' | 'collection'
```

Filters

Filter options that control which resources appear in the resource picker. Use filters to restrict the available resources based on publication status, resource type, or custom search criteria.

archived
Whether to include archived products in the picker. When `false`, archived products are hidden. When `undefined`, archived products appear with an archived badge. Only applies when `type` is `'product'`. Use this to prevent selecting discontinued products.
```
boolean | undefined
```
draft
Whether to include draft products in the picker. When `false`, draft products are hidden. When `undefined`, draft products appear with a draft badge. Only applies when `type` is `'product'`. Use this to prevent selecting products that aren't ready for use.
```
boolean | undefined
```
hidden
Whether to include products that aren't published on any sales channels. When `false`, only products published to at least one sales channel appear in the picker. Use this to ensure merchants only select products that customers can purchase.
```
boolean
```
query
A GraphQL search query that filters the available resources without showing the query in the picker's search bar. Merchants won't see or edit this filter. See [search syntax](/docs/api/usage/search-syntax) for the query format. Use this to programmatically restrict resources based on attributes like tags, vendor, or product type (for example, `"tag:featured"` or `"vendor:Acme"`).
```
string
```
variants
Whether to show product variants in the picker. When `false`, merchants can only select products, not individual variants. Only applies when `type` is `'product'`. Use this to simplify selection when you only need product-level data.
```
boolean
```

BaseResource

A resource that can have associated variants. Products and collections extend this interface.

id
The resource's unique global identifier (GID) in GraphQL format (for example, `'gid://shopify/Product/1'`). Use this to reference the resource in GraphQL queries.
```
string
```
variants
An array of variant resources associated with this resource. Use this for products that have multiple variants with different options.
```
Resource[]
```

Resource

A base resource with a unique identifier. All Shopify resources extend from this interface.

id
The resource's unique global identifier (GID) in GraphQL format (for example, `'gid://shopify/Product/1'`). Use this to reference the resource in GraphQL queries.
```
string
```

SelectPayload

The payload returned when resources are selected from the picker.

SelectPayload<Type>

AllComponents

The set of UI components available for all Admin UI extension targets. This includes all standard Polaris components except for specialized components used in specific contexts. Use this type to define which components can be rendered in your extension.

AnyComponentBuilder<
  Omit<
    Components,
    | 'CustomerSegmentTemplate'
    | 'InternalCustomerSegmentTemplate'
    | 'InternalLocationList'
  >
>

AnyComponentBuilder

AnyComponentBuilder<ComponentTypes>

ComponentTypes

typeof import('./components')

Components

AdminAction

"AdminAction" & { readonly type?: "AdminAction"; readonly props?: AdminActionProps; readonly children?: true; }

AdminBlock

"AdminBlock" & { readonly type?: "AdminBlock"; readonly props?: AdminBlockProps; readonly children?: true; }

AdminPrintAction

"AdminPrintAction" & { readonly type?: "AdminPrintAction"; readonly props?: AdminPrintActionProps; readonly children?: true; }

Badge

"Badge" & { readonly type?: "Badge"; readonly props?: BadgeProps; readonly children?: true; }

Banner

"Banner" & { readonly type?: "Banner"; readonly props?: BannerProps; readonly children?: true; }

BlockStack

"BlockStack" & { readonly type?: "BlockStack"; readonly props?: BlockStackProps; readonly children?: true; }

Box

"Box" & { readonly type?: "Box"; readonly props?: BoxProps; readonly children?: true; }

Button

"Button" & { readonly type?: "Button"; readonly props?: ButtonProps; readonly children?: true; }

Checkbox

"Checkbox" & { readonly type?: "Checkbox"; readonly props?: CheckboxProps; readonly children?: true; }

ChoiceList

"ChoiceList" & { readonly type?: "ChoiceList"; readonly props?: ChoiceListProps; readonly children?: true; }

ColorPicker

"ColorPicker" & { readonly type?: "ColorPicker"; readonly props?: ColorPickerProps; readonly children?: true; }

CustomerSegmentTemplate

"CustomerSegmentTemplate" & { readonly type?: "CustomerSegmentTemplate"; readonly props?: CustomerSegmentTemplateProps; readonly children?: true; }

DateField

"DateField" & { readonly type?: "DateField"; readonly props?: DateFieldProps; readonly children?: true; }

DatePicker

"DatePicker" & { readonly type?: "DatePicker"; readonly props?: DatePickerProps<Selected>; readonly children?: true; }

Divider

"Divider" & { readonly type?: "Divider"; readonly props?: DividerProps; readonly children?: true; }

EmailField

"EmailField" & { readonly type?: "EmailField"; readonly props?: EmailFieldProps; readonly children?: true; }

Form

"Form" & { readonly type?: "Form"; readonly props?: FormProps; readonly children?: true; }

FunctionSettings

"FunctionSettings" & { readonly type?: "FunctionSettings"; readonly props?: FunctionSettingsProps; readonly children?: true; }

Heading

"Heading" & { readonly type?: "Heading"; readonly props?: HeadingProps; readonly children?: true; }

HeadingGroup

"HeadingGroup" & { readonly type?: "HeadingGroup"; readonly props?: HeadingGroupProps; readonly children?: true; }

Icon

"Icon" & { readonly type?: "Icon"; readonly props?: IconProps; readonly children?: true; }

Image

"Image" & { readonly type?: "Image"; readonly props?: ImageProps; readonly children?: true; }

InlineStack

"InlineStack" & { readonly type?: "InlineStack"; readonly props?: InlineStackProps; readonly children?: true; }

InternalCustomerSegmentTemplate

"InternalCustomerSegmentTemplate" & { readonly type?: "InternalCustomerSegmentTemplate"; readonly props?: InternalCustomerSegmentTemplateProps; readonly children?: true; }

InternalLocationList

"InternalLocationList" & { readonly type?: "InternalLocationList"; readonly props?: InternalLocationListProps; readonly children?: true; }

Link

"Link" & { readonly type?: "Link"; readonly props?: LinkProps; readonly children?: true; }

MoneyField

"MoneyField" & { readonly type?: "MoneyField"; readonly props?: MoneyFieldProps; readonly children?: true; }

NumberField

"NumberField" & { readonly type?: "NumberField"; readonly props?: NumberFieldProps; readonly children?: true; }

Paragraph

"Paragraph" & { readonly type?: "Paragraph"; readonly props?: ParagraphProps; readonly children?: true; }

PasswordField

"PasswordField" & { readonly type?: "PasswordField"; readonly props?: PasswordFieldProps; readonly children?: true; }

Pressable

"Pressable" & { readonly type?: "Pressable"; readonly props?: PressableProps; readonly children?: true; }

ProgressIndicator

"ProgressIndicator" & { readonly type?: "ProgressIndicator"; readonly props?: ProgressIndicatorProps; readonly children?: true; }

Section

"Section" & { readonly type?: "Section"; readonly props?: SectionProps; readonly children?: true; }

Select

"Select" & { readonly type?: "Select"; readonly props?: SelectProps; readonly children?: true; }

Text

"Text" & { readonly type?: "Text"; readonly props?: TextProps; readonly children?: true; }

TextArea

"TextArea" & { readonly type?: "TextArea"; readonly props?: TextAreaProps; readonly children?: true; }

TextField

"TextField" & { readonly type?: "TextField"; readonly props?: TextFieldProps; readonly children?: true; }

URLField

"URLField" & { readonly type?: "URLField"; readonly props?: URLFieldProps; readonly children?: true; }

AdminActionProps

Props for the AdminAction component, used by Admin Action extensions to configure the title, primary and secondary action buttons, and loading state of the action modal.

loading
Whether the action modal is in a loading state. Set this to `true` while fetching data or processing a request to display a loading indicator in place of the modal's content.
```
boolean
```
primaryAction
The primary action button in the modal's footer, rendered as a Button. Use this for the main action the user can take, such as "Save" or "Submit".
```
RemoteFragment
```
secondaryAction
The secondary action button in the modal's footer, rendered as a Button. Use this for an alternative action, such as "Cancel" or "Discard".
```
RemoteFragment
```
title
The title displayed at the top of the action modal. If not provided, then the extension's name is used instead. Titles longer than 40 characters will be truncated.
```
string
```

AdminBlockProps

Props for the AdminBlock component, used by Admin Block extensions to configure the title and collapsed summary of an app block rendered on a resource page in the Shopify admin.

collapsedSummary
A short summary displayed when the app block is collapsed. Use this to give merchants a preview of the block's content without expanding it. Summaries longer than 30 characters will be truncated.
```
string
```
title
The title displayed at the top of the app block. If not provided, then the extension's name is used instead. Use this to give the block a contextual heading. Titles longer than 40 characters will be truncated.
```
string
```

AdminPrintActionProps

Props for the AdminPrintAction component, used by Admin Print Action extensions to configure a source document to preview and print.

src
The URL of the document to preview and print. Supported formats include HTML, PDF, and image files. If not provided, then the preview displays an empty state and the print button is disabled. Set this to the URL of the generated document once it's ready for the merchant to review and print.
```
string
```

BadgeProps

Props for the Badge component. A badge can optionally include an icon (`BadgeIconProps`) or omit one (`BadgeNoIconProps`). This union ensures type safety so that `iconPosition` can only be set when `icon` is present.

BadgeBaseProps & (BadgeIconProps | BadgeNoIconProps)

BadgeBaseProps

Base props shared by all Badge variants. Controls the semantic tone and size of the badge.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
size
The size of the badge. - `small-100`: A smaller badge, useful for compact layouts. - `base`: The standard badge size.
```
'base' | 'small-100'
```
tone
The color and semantic tone of the badge. Use this to communicate the status or importance of the information the badge represents. - `info`: Neutral informational content with no implied urgency. - `success`: A positive outcome or completed action. - `warning`: Something that needs attention but isn't blocking. - `critical`: A serious problem that needs immediate action.
```
Tone
```

BadgeIconProps

Props available when the badge displays an icon. When `icon` is set, you can also configure `iconPosition` to control where the icon appears.

icon
The name of the icon to display inside the badge. Use an icon to provide additional visual context alongside the badge text.
```
IconName
```
iconPosition
The position of the icon within the badge. Use `'end'` to place the icon after the badge text instead of before it. Requires `icon` to be set. - `start`: Icon appears before the text. - `end`: Icon appears after the text.
```
'start' | 'end'
```

IconName

The name of a Polaris icon. Each value corresponds to a specific icon from the Polaris icon set. Names follow the pattern `{IconName}{Major|Minor}`, where `Major` icons are intended for primary use and `Minor` icons are smaller variants for inline or secondary use.

'AbandonedCartFilledMajor' | 'AbandonedCartMajor' | 'AccessibilityMajor' | 'ActivitiesMajor' | 'AddCodeMajor' | 'AddImageMajor' | 'AddMajor' | 'AddNoteMajor' | 'AddProductMajor' | 'AdjustMinor' | 'AffiliateMajor' | 'AlertMinor' | 'AnalyticsBarHorizontalMinor' | 'AnalyticsBarStackedMinor' | 'AnalyticsCohortMinor' | 'AnalyticsDonutMinor' | 'AnalyticsFilledMinor' | 'AnalyticsFunnelMinor' | 'AnalyticsLineMinor' | 'AnalyticsMajor' | 'AnalyticsMinor' | 'AnalyticsTableMinor' | 'AnyClickModelMinor' | 'AppExtensionMinor' | 'AppsFilledMajor' | 'AppsMajor' | 'AppsMinor' | 'ArchiveMajor' | 'ArchiveMinor' | 'ArrowDownMinor' | 'ArrowLeftMinor' | 'ArrowRightMinor' | 'ArrowUpMinor' | 'AttachmentFilledMajor' | 'AttachmentMajor' | 'AutomationFilledMajor' | 'AutomationMajor' | 'BackspaceMajor' | 'BalanceFilledMajor' | 'BalanceMajor' | 'BankFilledMajor' | 'BankMajor' | 'BarcodeMajor' | 'BehaviorFilledMajor' | 'BehaviorMajor' | 'BehaviorMinor' | 'BillingStatementDollarFilledMajor' | 'BillingStatementDollarMajor' | 'BillingStatementEuroFilledMajor' | 'BillingStatementEuroMajor' | 'BillingStatementPoundFilledMajor' | 'BillingStatementPoundMajor' | 'BillingStatementRupeeFilledMajor' | 'BillingStatementRupeeMajor' | 'BillingStatementYenFilledMajor' | 'BillingStatementYenMajor' | 'BlockMinor' | 'BlockquoteMajor' | 'BlogMajor' | 'BoldMajor' | 'BoldMinor' | 'BugMajor' | 'ButtonCornerPillMajor' | 'ButtonCornerRoundedMajor' | 'ButtonCornerSquareMajor' | 'ButtonMinor' | 'BuyButtonButtonLayoutMajor' | 'BuyButtonHorizontalLayoutMajor' | 'BuyButtonMajor' | 'BuyButtonVerticalLayoutMajor' | 'CalendarMajor' | 'CalendarMinor' | 'CalendarTickMajor' | 'CalendarTimeMinor' | 'CameraMajor' | 'CancelMajor' | 'CancelMinor' | 'CancelSmallMinor' | 'CapitalFilledMajor' | 'CapitalMajor' | 'CapturePaymentMinor' | 'CardReaderChipMajor' | 'CardReaderMajor' | 'CardReaderTapMajor' | 'CaretDownMinor' | 'CaretUpMinor' | 'CartDownFilledMajor' | 'CartDownMajor' | 'CartFilledMajor' | 'CartMajor' | 'CartUpMajor' | 'CashDollarFilledMajor' | 'CashDollarMajor' | 'CashDollarMinor' | 'CashEuroMajor' | 'CashPoundMajor' | 'CashRupeeMajor' | 'CashYenMajor' | 'CategoriesMajor' | 'ChannelsMajor' | 'ChatMajor' | 'ChecklistAlternateMajor' | 'ChecklistMajor' | 'CheckoutMajor' | 'ChevronDownMinor' | 'ChevronLeftMinor' | 'ChevronRightMinor' | 'ChevronUpMinor' | 'CircleAlertMajor' | 'CircleCancelMajor' | 'CircleCancelMinor' | 'CircleChevronDownMinor' | 'CircleChevronLeftMinor' | 'CircleChevronRightMinor' | 'CircleChevronUpMinor' | 'CircleDisableMinor' | 'CircleDisabledMajor' | 'CircleDotsMajor' | 'CircleDownMajor' | 'CircleInformationMajor' | 'CircleLeftMajor' | 'CircleMinusMajor' | 'CircleMinusMinor' | 'CircleMinusOutlineMinor' | 'CirclePlusMajor' | 'CirclePlusMinor' | 'CirclePlusOutlineMinor' | 'CircleRightMajor' | 'CircleTickMajor' | 'CircleTickMinor' | 'CircleTickOutlineMinor' | 'CircleUpMajor' | 'ClipboardMinor' | 'ClockMajor' | 'ClockMinor' | 'CodeMajor' | 'CodeMinor' | 'CollectionReferenceMinor' | 'CollectionsFilledMajor' | 'CollectionsMajor' | 'ColorNoneMinor' | 'ColorsMajor' | 'Column1Major' | 'ColumnWithTextMajor' | 'Columns2Major' | 'Columns3Major' | 'Columns3Minor' | 'ComposeMajor' | 'ConfettiMajor' | 'ConnectMinor' | 'ContentFilledMinor' | 'ContentMinor' | 'ConversationMinor' | 'CreditCardCancelMajor' | 'CreditCardMajor' | 'CreditCardPercentMajor' | 'CreditCardSecureMajor' | 'CurrencyConvertMinor' | 'CustomerMinusMajor' | 'CustomerPlusMajor' | 'CustomersFilledMinor' | 'CustomersMajor' | 'CustomersMinor' | 'DataDrivenModelMinor' | 'DataVisualizationMajor' | 'DecimalMinor' | 'DeleteMajor' | 'DeleteMinor' | 'DesktopMajor' | 'DetailedPopUpMajor' | 'DiamondAlertMajor' | 'DiamondAlertMinor' | 'DigitalMediaReceiverMajor' | 'DiscountAutomaticMajor' | 'DiscountCodeMajor' | 'DiscountsFilledMinor' | 'DiscountsMajor' | 'DiscountsMinor' | 'DisputeMinor' | 'DnsSettingsMajor' | 'DockFloatingMajor' | 'DockSideMajor' | 'DomainNewMajor' | 'DomainRedirectMinor' | 'DomainsFilledMajor' | 'DomainsMajor' | 'DraftOrdersFilledMajor' | 'DraftOrdersMajor' | 'DragDropMajor' | 'DragHandleMinor' | 'DropdownMinor' | 'DuplicateMinor' | 'DynamicSourceMajor' | 'DynamicSourceMinor' | 'EditMajor' | 'EditMinor' | 'EmailMajor' | 'EmailNewsletterMajor' | 'EmbedMinor' | 'EnableSelectionMinor' | 'EnterMajor' | 'EnvelopeMajor' | 'ExchangeMajor' | 'ExistingInventoryMajor' | 'ExitMajor' | 'ExploreImagesMajor' | 'ExportMinor' | 'ExtendMajor' | 'ExtendMinor' | 'ExternalMinor' | 'ExternalSmallMinor' | 'EyeDropperMinor' | 'FaviconMajor' | 'FavoriteMajor' | 'FeaturedCollectionMajor' | 'FeaturedContentMajor' | 'FileFilledMinor' | 'FileMinor' | 'FilterMajor' | 'FilterMinor' | 'FinancesMajor' | 'FinancesMinor' | 'FirstClickModelMinor' | 'FirstOrderMajor' | 'FirstVisitMajor' | 'FlagMajor' | 'FlipCameraMajor' | 'FolderDownMajor' | 'FolderMajor' | 'FolderMinusMajor' | 'FolderPlusMajor' | 'FolderUpMajor' | 'FollowUpEmailMajor' | 'FoodMajor' | 'FooterMajor' | 'FormsMajor' | 'FraudProtectMajor' | 'FraudProtectMinor' | 'FraudProtectPendingMajor' | 'FraudProtectPendingMinor' | 'FraudProtectUnprotectedMajor' | 'FraudProtectUnprotectedMinor' | 'FulfillmentFulfilledMajor' | 'FulfillmentOnHoldMajor' | 'GamesConsoleMajor' | 'GaugeMajor' | 'GaugeMinor' | 'GiftCardFilledMinor' | 'GiftCardMajor' | 'GiftCardMinor' | 'GlobeMajor' | 'GlobeMinor' | 'GrammarMajor' | 'HashtagMajor' | 'HashtagMinor' | 'HeaderMajor' | 'HeartMajor' | 'HideKeyboardMajor' | 'HideMinor' | 'HintMajor' | 'HomeFilledMinor' | 'HomeMajor' | 'HomeMinor' | 'HorizontalDotsMinor' | 'IconNameSet' | 'IconsFilledMajor' | 'IconsMajor' | 'IdentityCardFilledMajor' | 'IdentityCardMajor' | 'IllustrationMajor' | 'ImageAltMajor' | 'ImageAltMinor' | 'ImageMajor' | 'ImageWithTextMajor' | 'ImageWithTextOverlayMajor' | 'ImagesMajor' | 'ImportMinor' | 'ImportStoreMajor' | 'InactiveLocationMajor' | 'InactiveLocationMinor' | 'IncomingMajor' | 'IndentMajor' | 'IndentMinor' | 'InfoMinor' | 'InsertDynamicSourceMajor' | 'InsertDynamicSourceMinor' | 'InstallMinor' | 'InventoryFilledMajor' | 'InventoryMajor' | 'InviteMinor' | 'IqMajor' | 'ItalicMajor' | 'ItalicMinor' | 'JobsFilledMajor' | 'JobsMajor' | 'KeyMajor' | 'KeyboardMajor' | 'KeyboardMinor' | 'LabelPrinterMajor' | 'LandingPageMajor' | 'LanguageFilledMinor' | 'LanguageMinor' | 'LastClickModelMinor' | 'LastNonDirectClickModelMinor' | 'LegalFilledMajor' | 'LegalMajor' | 'LinearModelMinor' | 'LinkMinor' | 'ListFilledMajor' | 'ListMajor' | 'ListMinor' | 'LiveViewFilledMajor' | 'LiveViewMajor' | 'LocationFilledMajor' | 'LocationMajor' | 'LocationsMinor' | 'LockFilledMajor' | 'LockMajor' | 'LockMinor' | 'LogOutMinor' | 'LogoBlockMajor' | 'MagicMajor' | 'MagicMinor' | 'ManagedStoreMajor' | 'MarkFulfilledMinor' | 'MarkPaidMinor' | 'MarketingFilledMinor' | 'MarketingMajor' | 'MarketingMinor' | 'MarketsFilledMajor' | 'MarketsMajor' | 'MaximizeMajor' | 'MaximizeMinor' | 'MeasurementMinor' | 'MentionMajor' | 'MergeMinor' | 'MetafieldsFilledMinor' | 'MetafieldsMajor' | 'MetafieldsMinor' | 'MetaobjectMinor' | 'MetaobjectReferenceMinor' | 'MicrophoneMajor' | 'MinimizeMajor' | 'MinimizeMinor' | 'MinusMajor' | 'MinusMinor' | 'MobileAcceptMajor' | 'MobileBackArrowMajor' | 'MobileCancelMajor' | 'MobileChevronMajor' | 'MobileHamburgerMajor' | 'MobileHorizontalDotsMajor' | 'MobileMajor' | 'MobilePlusMajor' | 'MobileVerticalDotsMajor' | 'MonerisMajor' | 'MoneyFilledMinor' | 'MoneyMinor' | 'NatureMajor' | 'NavigationMajor' | 'NoteMajor' | 'NoteMinor' | 'NotificationFilledMajor' | 'NotificationMajor' | 'OnlineStoreMajor' | 'OnlineStoreMinor' | 'OrderStatusMinor' | 'OrderedListMajor' | 'OrderedListMinor' | 'OrdersFilledMinor' | 'OrdersMajor' | 'OrdersMinor' | 'OrganizationMajor' | 'OutdentMajor' | 'OutdentMinor' | 'OutgoingMajor' | 'PackageFilledMajor' | 'PackageMajor' | 'PageDownMajor' | 'PageMajor' | 'PageMinusMajor' | 'PagePlusMajor' | 'PageReferenceMinor' | 'PageUpMajor' | 'PaginationEndMinor' | 'PaginationStartMinor' | 'PaintBrushMajor' | 'PaperCheckMajor' | 'PaperCheckMinor' | 'PasskeyFilledMinor' | 'PasskeyMajor' | 'PasskeyMinor' | 'PauseCircleMajor' | 'PauseMajor' | 'PauseMinor' | 'PaymentsFilledMajor' | 'PaymentsMajor' | 'PersonalizedTextMajor' | 'PhoneInMajor' | 'PhoneMajor' | 'PhoneOutMajor' | 'PinMajor' | 'PinMinor' | 'PinUnfilledMajor' | 'PinUnfilledMinor' | 'PlanFilledMinor' | 'PlanMajor' | 'PlanMinor' | 'PlayCircleMajor' | 'PlayMajor' | 'PlayMinor' | 'PlusMinor' | 'PointOfSaleMajor' | 'PopularMajor' | 'PositionBasedModelMinor' | 'PriceLookupMinor' | 'PrintMajor' | 'PrintMinor' | 'ProductCostMajor' | 'ProductReferenceMinor' | 'ProductReturnsMinor' | 'ProductsFilledMinor' | 'ProductsMajor' | 'ProductsMinor' | 'ProfileMajor' | 'ProfileMinor' | 'PromoteFilledMinor' | 'PromoteMinor' | 'QuestionMarkInverseMajor' | 'QuestionMarkInverseMinor' | 'QuestionMarkMajor' | 'QuestionMarkMinor' | 'QuickSaleMajor' | 'ReadTimeMinor' | 'ReceiptMajor' | 'RecentSearchesMajor' | 'RedoMajor' | 'ReferralCodeMajor' | 'ReferralMajor' | 'RefreshMajor' | 'RefreshMinor' | 'RefundMajor' | 'RefundMinor' | 'RemoveProductMajor' | 'RepeatOrderMajor' | 'ReplaceMajor' | 'ReplayMinor' | 'ReportFilledMinor' | 'ReportMinor' | 'ReportsMajor' | 'ResetMinor' | 'ResourcesMajor' | 'ReturnMinor' | 'ReturnsMajor' | 'RichTextMinor' | 'RiskMajor' | 'RiskMinor' | 'Rows2Major' | 'SandboxMajor' | 'SaveMinor' | 'SearchMajor' | 'SearchMinor' | 'SectionMajor' | 'SecureMajor' | 'SelectMinor' | 'SendMajor' | 'SettingsFilledMinor' | 'SettingsMajor' | 'SettingsMinor' | 'ShareIosMinor' | 'ShareMinor' | 'ShipmentFilledMajor' | 'ShipmentMajor' | 'ShopcodesMajor' | 'SidebarLeftMajor' | 'SidebarRightMajor' | 'SimplifyMajor' | 'SimplifyMinor' | 'SlideshowMajor' | 'SmileyHappyMajor' | 'SmileyJoyMajor' | 'SmileyNeutralMajor' | 'SmileySadMajor' | 'SocialAdMajor' | 'SocialPostMajor' | 'SoftPackMajor' | 'SortAscendingMajor' | 'SortDescendingMajor' | 'SortMinor' | 'SoundMajor' | 'StarFilledMinor' | 'StarOutlineMinor' | 'StatusActiveMajor' | 'StopMajor' | 'StoreDetailsFilledMinor' | 'StoreDetailsMinor' | 'StoreFilledMinor' | 'StoreMajor' | 'StoreMinor' | 'StoreStatusMajor' | 'TabletMajor' | 'TapChipMajor' | 'TaxFilledMajor' | 'TaxMajor' | 'TeamMajor' | 'TemplateMajor' | 'TemplateMinor' | 'TextAlignmentCenterMajor' | 'TextAlignmentLeftMajor' | 'TextAlignmentRightMajor' | 'TextBlockMajor' | 'TextColorMajor' | 'TextColorMinor' | 'TextMajor' | 'ThemeEditMajor' | 'ThemeStoreMajor' | 'ThemesMajor' | 'ThumbsDownMajor' | 'ThumbsDownMinor' | 'ThumbsUpMajor' | 'ThumbsUpMinor' | 'TickMinor' | 'TickSmallMinor' | 'TimeDecayModelMinor' | 'TimelineAttachmentMajor' | 'TipsMajor' | 'TitleMinor' | 'ToggleMinor' | 'ToolsMajor' | 'TransactionFeeDollarMajor' | 'TransactionFeeEuroMajor' | 'TransactionFeePoundMajor' | 'TransactionFeeRupeeMajor' | 'TransactionFeeYenMajor' | 'TransactionMajor' | 'TransferFilledMajor' | 'TransferInMajor' | 'TransferMajor' | 'TransferOutMajor' | 'TransferWithinShopifyMajor' | 'TransportMajor' | 'TroubleshootMajor' | 'TypeMajor' | 'TypeMinor' | 'UnderlineMajor' | 'UnderlineMinor' | 'UndoMajor' | 'UnfulfilledMajor' | 'UnknownDeviceMajor' | 'UpdateInventoryMajor' | 'UploadMajor' | 'VariantMajor' | 'ViewMajor' | 'ViewMinor' | 'ViewportNarrowMajor' | 'ViewportShortMajor' | 'ViewportTallMajor' | 'ViewportWideMajor' | 'VocabularyMajor' | 'VolumeMinor' | 'WandMajor' | 'WandMinor' | 'WearableMajor' | 'WeightMinor' | 'WholesaleMajor' | 'WifiMajor'

BadgeNoIconProps

Props for a badge without an icon. These properties are typed as `never` to ensure that `icon` and `iconPosition` can't be set when no icon is intended. This creates a discriminated union with `BadgeIconProps`.

icon
The name of the icon to display inside the badge. Typed as `never` on this variant because no icon is provided. Use the `BadgeIconProps` variant to set an icon.
```
never
```
iconPosition
The position of the icon within the badge. Typed as `never` on this variant because no icon is provided. Set `icon` first to configure its position.
```
never
```

BannerProps

Props for the Banner component, which displays a prominent message to the merchant. Banners communicate important information, status updates, warnings, or errors, with optional primary and secondary actions.

dismissible
Whether the banner can be dismissed by the merchant. When `true`, then a close button is rendered that allows the merchant to hide the banner.
```
boolean
```
id
A unique identifier for the element.
```
string
```
onDismiss
A callback fired when the merchant dismisses the banner by pressing the close button. Use this to update your state and stop rendering the banner. Only relevant when `dismissible` is `true`.
```
() => void
```
primaryAction
The primary action for the banner, rendered as a Button. Use this for the main action related to the banner message, such as "Review" or "Fix issue".
```
RemoteFragment
```
secondaryAction
The secondary action for the banner, rendered as a Button. Use this for an alternative or less prominent action, such as "Learn more" or "Dismiss".
```
RemoteFragment
```
title
The main message displayed inside the banner. Use this to communicate important information, status updates, or actionable messages to the merchant.
```
string
```
tone
The color and icon of the banner, conveying its semantic meaning.
```
Tone
```

BlockStackProps

Props for the BlockStack component, which arranges its children in a vertical stack (block axis). Use BlockStack to lay out components vertically with consistent spacing and alignment.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.
```
AccessibilityRole
```
blockAlignment
The alignment of children along the block (vertical) axis within the stack. Use this to control how children are vertically distributed in a vertical stack layout.
```
MainAxisAlignment
```
blockGap
The spacing between children along the block axis (top-to-bottom in horizontal writing modes). This is an alias for `rowGap`. When set to `true`, applies a default block gap appropriate for the component.
```
SpacingKeyword | boolean
```
blockSize
The block size (height in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size) property.
```
number | `${number}%`
```
gap
The spacing between children in both axes. Accepts a single value for uniform spacing, or two values separated by a space for independent block-axis and inline-axis spacing (such as `"base small"`). When set to `true`, applies a default gap appropriate for the component. Learn more about the [gap](https://developer.mozilla.org/en-US/docs/Web/CSS/gap) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
id
A unique identifier for the element.
```
string
```
inlineAlignment
The alignment of children along the inline (horizontal) axis within the stack. Use this to control how children are horizontally aligned in a vertical stack layout.
```
CrossAxisAlignment
```
inlineSize
The inline size (width in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) property.
```
number | `${number}%`
```
maxBlockSize
The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [max-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) property.
```
number | `${number}%`
```
maxInlineSize
The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property.
```
number | `${number}%`
```
minBlockSize
The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [min-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) property.
```
number | `${number}%`
```
minInlineSize
The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property.
```
number | `${number}%`
```
padding
The padding on all edges of the element, using a shorthand syntax. You can specify one to four values following the [CSS shorthand convention](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box). When set to `true`, applies a default padding appropriate for the component.
```
MaybeAllBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlock
The padding on the block-start and block-end edges. When set to `true`, applies a default block padding appropriate for the component. Learn more about the [padding-block](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlockEnd
The padding on the block-end edge (the bottom edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-end) property.
```
SpacingKeyword | boolean
```
paddingBlockStart
The padding on the block-start edge (the top edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-start) property.
```
SpacingKeyword | boolean
```
paddingInline
The padding on the inline-start and inline-end edges. When set to `true`, applies a default inline padding appropriate for the component. Learn more about the [padding-inline](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingInlineEnd
The padding on the inline-end edge (the right edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-end) property.
```
SpacingKeyword | boolean
```
paddingInlineStart
The padding on the inline-start edge (the left edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-start) property.
```
SpacingKeyword | boolean
```
rowGap
The spacing between rows (children stacked along the block axis). When set to `true`, applies a default row gap appropriate for the component. Learn more about the [row-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap) property.
```
SpacingKeyword | boolean
```

AccessibilityRole

The set of accessibility roles that can be applied to layout components to convey semantic meaning to assistive technologies. Each role maps to a corresponding HTML element or ARIA role in web-based hosts. - `main`: The primary content of the page. - `header`: A header section of the page. - `footer`: A section for copyright information, navigation links, and privacy statements. - `section`: A generic section; should have a heading or accessible label. - `aside`: A supporting section related to the main content. - `navigation`: A major group of navigation links. - `ordered-list`: A list of ordered items. - `list-item`: An item inside a list. - `list-item-separator`: A divider that separates items in a list. - `unordered-list`: A list of unordered items. - `separator`: A divider separating sections of content. - `status`: A live region with advisory information that isn't urgent enough to be an alert. - `alert`: Important, usually time-sensitive information. - `generic`: A nameless container with no semantic meaning on its own.

'main' | 'header' | 'footer' | 'section' | 'aside' | 'navigation' | 'ordered-list' | 'list-item' | 'list-item-separator' | 'unordered-list' | 'separator' | 'status' | 'alert' | 'generic'

MainAxisAlignment

Controls how items are distributed along the container's main axis (the primary stacking direction). - `start`: Items are packed toward the start of the main axis. - `center`: Items are centered along the main axis. - `end`: Items are packed toward the end of the main axis. - `space-between`: Items are distributed evenly. The first item is flush with the start edge, the last with the end edge. - `space-around`: Items are distributed evenly with half-size spaces on both ends. - `space-evenly`: Items are distributed so that spacing between any two adjacent items (and edges) is equal. Learn more about the [justify-content](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content) property.

'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly'

SpacingKeyword

A keyword that maps to a predefined spacing value from the Shopify admin design system. Use these instead of pixel values to ensure consistent spacing throughout the UI. - `none`: No spacing (0px). - `small`: A compact amount of spacing, suitable for tight layouts. - `base`: The default spacing, appropriate for most layouts. - `large`: A generous amount of spacing, used to create visual separation.

'none' | 'small' | 'base' | 'large'

MaybeTwoBoxEdgesShorthandProperty

A shorthand type that accepts one or two spacing values, representing the start and end edges of a single axis (block or inline). - One value (such as `base`): Applied to both the start and end edges. - Two values (such as `base none`): The first is applied to the start edge, the second to the end edge.

T | `${T} ${T}`

CrossAxisAlignment

Controls how items are aligned along the container's cross axis (perpendicular to the main stacking direction). - `start`: Items are aligned to the start of the container's cross axis. - `center`: Items are centered along the container's cross axis. - `end`: Items are aligned to the end of the container's cross axis. - `baseline`: Items are aligned so their text baselines line up with each other. Learn more about the [align-items](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items) property.

'start' | 'center' | 'end' | 'baseline'

MaybeAllBoxEdgesShorthandProperty

A shorthand type that accepts one to four spacing values following the CSS box-edge shorthand convention (block-start, inline-end, block-end, inline-start). - One value (such as `base`): Applied to all four edges. - Two values (such as `base none`): The first is applied to block-start and block-end, the second to inline-start and inline-end. - Three values (such as `base none large`): The first is block-start, the second is inline-start and inline-end, the third is block-end. - Four values (such as `base none large small`): Applied to block-start, inline-end, block-end, and inline-start respectively.

T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`

BoxProps

Props for the Box component, a generic layout container. Box doesn't define any props of its own. It inherits accessibility, sizing, padding, and display props from shared interfaces.

accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.
```
AccessibilityRole
```
blockSize
The block size (height in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size) property.
```
number | `${number}%`
```
display
Whether the element is rendered and takes up space in the layout. - `auto`: The element is rendered normally and participates in layout. - `none`: The element isn't rendered at all and doesn't take up any space. Use this to conditionally hide content without removing it from the component tree.
```
'auto' | 'none'
```
inlineSize
The inline size (width in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) property.
```
number | `${number}%`
```
maxBlockSize
The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [max-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) property.
```
number | `${number}%`
```
maxInlineSize
The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property.
```
number | `${number}%`
```
minBlockSize
The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [min-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) property.
```
number | `${number}%`
```
minInlineSize
The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property.
```
number | `${number}%`
```
padding
The padding on all edges of the element, using a shorthand syntax. You can specify one to four values following the [CSS shorthand convention](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box). When set to `true`, applies a default padding appropriate for the component.
```
MaybeAllBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlock
The padding on the block-start and block-end edges. When set to `true`, applies a default block padding appropriate for the component. Learn more about the [padding-block](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlockEnd
The padding on the block-end edge (the bottom edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-end) property.
```
SpacingKeyword | boolean
```
paddingBlockStart
The padding on the block-start edge (the top edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-start) property.
```
SpacingKeyword | boolean
```
paddingInline
The padding on the inline-start and inline-end edges. When set to `true`, applies a default inline padding appropriate for the component. Learn more about the [padding-inline](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingInlineEnd
The padding on the inline-end edge (the right edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-end) property.
```
SpacingKeyword | boolean
```
paddingInlineStart
The padding on the inline-start edge (the left edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-start) property.
```
SpacingKeyword | boolean
```

ButtonProps

Props for the Button component. A button can either be a standard action button (`ButtonBaseProps`) or an anchor-style button that navigates to a URL (`ButtonAnchorProps`).

ButtonBaseProps | ButtonAnchorProps

ButtonBaseProps

Props for a standard action button that triggers behavior when pressed. Extends `CommonProps` and adds an `accessibilityRole` to control the semantic role (button, submit, or reset).

accessibilityLabel
A label read by assistive technologies like screen readers to describe the button's purpose. Use this when the button contains only an icon or when the visible text doesn't provide enough context on its own for users who can't see the button.
```
string
```
accessibilityRole
The semantic role of the button for assistive technologies. - `submit`: Submits the nearest containing form when pressed. - `button`: A standard button that triggers an action (default). - `reset`: Resets the nearest containing form to its default values.
disabled
Whether the button is disabled. When `true`, the button can't be interacted with and is rendered in a visually muted style to indicate it isn't available.
```
boolean
```
id
A unique identifier for the button. Use this when you need to reference the button programmatically or distinguish it from other buttons in the same view.
```
string
```
lang
An alias for `language`. The language of the button's text content. Use this when the button text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
language
The language of the button's text content. Use this when the button text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
onBlur
A callback fired when the button loses focus. Use this to trigger validation or other logic when the merchant moves away from the button.
```
() => void
```
onClick
A callback fired when the button is pressed. If `href` is set, the callback runs first, then the navigation occurs.
```
() => void
```
onFocus
A callback fired when the button receives focus. Use this to trigger logic when the merchant focuses the button through keyboard navigation or other input methods.
```
() => void
```
onPress
An alias for `onClick`. A callback fired when the button is pressed. If `href` is set, the callback runs first, then the navigation occurs.
```
() => void
```
tone
The color treatment of the button, used to convey its intent. - `default`: Standard button color for general actions. - `critical`: Red coloring to indicate a destructive or irreversible action, such as deleting a resource.
```
'default' | 'critical'
```
variant
The visual style of the button, used to convey its level of emphasis. - `primary`: A high-emphasis button for the main action in a section. - `secondary`: A medium-emphasis button for supporting actions. - `tertiary`: A low-emphasis button for less prominent actions, rendered as a plain text link-style button.
```
'primary' | 'secondary' | 'tertiary'
```

ButtonAnchorProps

Props for an anchor-style button that navigates to a URL when pressed. Extends `CommonProps` and adds link-specific properties like `href`, `target`, and `download`.

accessibilityLabel
A label read by assistive technologies like screen readers to describe the button's purpose. Use this when the button contains only an icon or when the visible text doesn't provide enough context on its own for users who can't see the button.
```
string
```
disabled
Whether the button is disabled. When `true`, the button can't be interacted with and is rendered in a visually muted style to indicate it isn't available.
```
boolean
```
download
When set, the linked resource is downloaded instead of being navigated to. Pass a string to specify a custom filename for the downloaded file, or `true` to use the default filename.
```
boolean | string
```
href
The URL to navigate to when the button is pressed. When set, the button behaves as a link. If an `onClick` callback is also provided, it runs first, then the navigation occurs.
```
string
```
id
A unique identifier for the button. Use this when you need to reference the button programmatically or distinguish it from other buttons in the same view.
```
string
```
lang
An alias for `language`. The language of the button's text content. Use this when the button text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
language
The language of the button's text content. Use this when the button text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
onBlur
A callback fired when the button loses focus. Use this to trigger validation or other logic when the merchant moves away from the button.
```
() => void
```
onClick
A callback fired when the link button is pressed. The callback runs first, then the navigation to `href` occurs.
```
() => void
```
onFocus
A callback fired when the button receives focus. Use this to trigger logic when the merchant focuses the button through keyboard navigation or other input methods.
```
() => void
```
onPress
An alias for `onClick`. A callback fired when the link button is pressed. The callback runs first, then the navigation to `href` occurs.
```
() => void
```
target
The browsing context in which to open the linked URL. - `_blank`: Opens in a new tab or window. - `_self`: Opens in the same context (default).
```
'_blank' | '_self'
```
to
An alias for `href`. The URL to navigate to when the button is pressed.
```
string
```
tone
The color treatment of the button, used to convey its intent. - `default`: Standard button color for general actions. - `critical`: Red coloring to indicate a destructive or irreversible action, such as deleting a resource.
```
'default' | 'critical'
```
variant
The visual style of the button, used to convey its level of emphasis. - `primary`: A high-emphasis button for the main action in a section. - `secondary`: A medium-emphasis button for supporting actions. - `tertiary`: A low-emphasis button for less prominent actions, rendered as a plain text link-style button.
```
'primary' | 'secondary' | 'tertiary'
```

CheckboxProps

Props for the Checkbox component, which renders a toggleable input that lets the merchant choose between a checked and unchecked state.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
checked
Whether the checkbox is currently checked. This is a controlled prop, so you must update it in response to `onChange` to reflect the new state.
```
boolean
```
disabled
Whether the checkbox is disabled. When `true`, then the checkbox can't be interacted with and appears in a muted style to indicate it isn't available.
```
boolean
```
error
An error message displayed below the checkbox. When set, the checkbox receives a specific visual treatment to indicate a problem that the merchant needs to resolve before continuing.
```
string
```
id
A unique identifier for the checkbox. When no `id` is set, a globally unique value is generated automatically.
```
string
```
label
The text label displayed next to the checkbox. Use this to clearly describe what the checkbox controls.
```
string
```
name
An identifier for the checkbox that is unique within the nearest containing Form component. Use this to identify the checkbox's value when the form is submitted.
```
string
```
onChange
A callback fired whenever the checkbox's checked state changes. The callback receives a boolean indicating the new checked state. Because this is a controlled component, you must store this value in state and reflect it back in the `checked` or `value` prop.
```
(value: boolean) => void
```
value
Whether the checkbox is checked. This is an alias for `checked` and can be useful in form libraries that provide a normalized API for handling both `boolean` and `string` values. If both `value` and `checked` are set, then `checked` takes precedence.
```
boolean
```

ChoiceListProps

Props for the ChoiceList component, which renders a group of selectable choices as either radio buttons (single selection) or checkboxes (multiple selection).

choices
The list of choices to render. Each choice is an object with properties like `label`, `id`, `disabled`, `readOnly`, `error`, and `checked`. Provide at least two choices for meaningful selection.
```
ChoiceProps[]
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
multiple
Whether the merchant can select more than one choice. When `true`, then each choice is rendered as a checkbox. When `false`, then choices are rendered as radio buttons and only one can be selected at a time.
```
boolean
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string | string[]) => void
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

ChoiceProps

Props for an individual choice within a ChoiceList. Each choice represents a selectable option rendered as either a radio button or a checkbox, depending on the `multiple` setting of the parent ChoiceList.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
checked
Whether this individual choice is checked. Use this to pre-select a specific option when the choice list is first rendered.
```
boolean
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```

ColorPickerProps

Props for the ColorPicker component, which provides a visual interface for the merchant to select a color, with optional alpha (transparency) support.

allowAlpha
Whether to show an alpha (transparency) slider, allowing the merchant to select a color with transparency. When `true`, then `onChange` emits an 8-character hex string (`#RRGGBBAA`). When `false`, then `onChange` emits a 6-character hex string (`#RRGGBB`).
```
boolean
```
id
A unique identifier for the color picker. Use this when you need to reference the component programmatically or for form association.
```
string
```
onChange
A callback fired when the merchant selects a new color. The value is always emitted as a hex string. If `allowAlpha` is `true`, then the value is an 8-character hex (`#RRGGBBAA`). If `allowAlpha` is `false`, then the value is a 6-character hex (`#RRGGBB`).
```
(value: string) => void
```
value
The currently selected color value. Accepts [hex](https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color), [rgb, and rgba](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb) strings. Defaults to `rgb(0, 0, 0)` if the value is invalid.
```
string
```

CustomerSegmentTemplateProps

Props for the CustomerSegmentTemplate component, which defines a reusable segment template that merchants can apply in the customer segment editor.

createdOn
The date the template was introduced, as an ISO 8601 string (such as `'2025-01-15'`). Templates created within the last month display a "New" badge.
```
string
```
dependencies
The metafields that the template's query depends on. Declaring dependencies lets the admin verify that the required metafield definitions exist before the merchant applies the template.
```
{ standardMetafields?: "facts.birth_date"[]; customMetafields?: string[]; }
```
description
The localized description displayed below the title. Explains what customers the segment targets. Pass an array of strings to render multiple paragraphs.
```
string | string[]
```
query
The segment query displayed on the template card with syntax highlighting. This query isn't validated at render time.
```
string
```
queryToInsert
The segment query inserted into the editor when the merchant applies the template. Defaults to `query` if not provided. This query isn't validated at render time.
```
string
```
title
The localized title displayed on the template card, such as "Customers with birthdays this month".
```
string
```

DateFieldProps

Props for the DateField component, which combines a text input with a calendar picker for date selection. Text input props (like `label`, `value`, `onChange`, and `error`) come from `TextFieldProps`, while calendar navigation props (like `yearMonth`, `disabled`, and `onYearMonthChange`) come from `DatePickerProps`.

defaultYearMonth
The year and month to display when the calendar first renders. Use this for an uncontrolled calendar that manages its own navigation state. This prop is ignored when `yearMonth` is set (controlled mode). Accepts either an object (`{ year, month }`) or a `YYYY-MM` string.
```
{year: Year; month: Month} | YearMonthString
```
disabled
The dates that the user can't select. - `DateString`: Disables a specific date, such as `'2024-12-25'`. - `Range`: Disables a span of dates between `start` and `end`. Omit `start` or `end` for an open-ended range. - `Day`: Disables every occurrence of a weekday, such as `'Sunday'`. - `Disabled[]`: An array combining any of the above. - `true`: Disables the entire date picker.
```
Disabled | Disabled[] | boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
onYearMonthChange
A callback that fires when the user navigates to a different month or year (for example, by pressing the forward/back arrows). Receives an object with `year` and `month` properties. When using controlled navigation (`yearMonth` is set), you must update your state and pass the new value back through the `yearMonth` prop.
```
(yearMonth: { year: number; month: number; }) => void
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```
yearMonth
The year and month currently displayed in the calendar. Use this prop together with `onYearMonthChange` to control which month the user sees. When set, the calendar won't navigate on its own. You must update this value in response to `onYearMonthChange` to let the user browse months. Accepts either an object (`{ year, month }`) or a `YYYY-MM` string.
```
{year: Year; month: Month} | YearMonthString
```

Year

A four-digit year number, for example `2024`.

number

Month

A month number in the 1–12 range (1 = January, 12 = December).

number

YearMonthString

A year-and-month string in simplified ISO 8601 format (`YYYY-MM`), for example `'2024-12'`.

string

Disabled

A value that can be disabled in the date picker. Can be a specific `DateString`, a `Range` of dates, or a `Day` of the week.

DateString | Range | Day

DateString

A date string in simplified ISO 8601 format (`YYYY-MM-DD`), for example `'2024-12-25'`.

string

Range

A date range with optional start and end boundaries. Used for range selection in the date picker or for disabling a span of dates. Omitting `start` or `end` creates an open-ended range.

end
The last day (inclusive) of the selected range.
```
DateString
```
start
The first day (inclusive) of the selected range.
```
DateString
```

Day

A day of the week. Used in `disabled` to disable every occurrence of a specific weekday (for example, `'Sunday'` disables all Sundays).

'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday'

DatePickerProps

Props for the DatePicker component, a calendar-based date selection control. The generic parameter `T` determines the selection mode: pass a `DateString` for single-date, a `DateString[]` for multi-date, or a `Range` for range selection.

defaultYearMonth
The year and month to display when the calendar first renders. Use this for an uncontrolled calendar that manages its own navigation state. This prop is ignored when `yearMonth` is set (controlled mode). Accepts either an object (`{ year, month }`) or a `YYYY-MM` string.
```
{year: Year; month: Month} | YearMonthString
```
disabled
The dates that the user can't select. - `DateString`: Disables a specific date, such as `'2024-12-25'`. - `Range`: Disables a span of dates between `start` and `end`. Omit `start` or `end` for an open-ended range. - `Day`: Disables every occurrence of a weekday, such as `'Sunday'`. - `Disabled[]`: An array combining any of the above. - `true`: Disables the entire date picker.
```
Disabled | Disabled[] | boolean
```
onChange
A callback that fires when the user selects or deselects a date. Receives the new selection value matching the shape of `selected` (a string, an array of strings, or a `Range` object). You must store this value in state and pass it back through the `selected` prop.
```
(selected: T) => void
```
onYearMonthChange
A callback that fires when the user navigates to a different month or year (for example, by pressing the forward/back arrows). Receives an object with `year` and `month` properties. When using controlled navigation (`yearMonth` is set), you must update your state and pass the new value back through the `yearMonth` prop.
```
(yearMonth: { year: number; month: number; }) => void
```
readOnly
Whether the date picker is read-only. When `true`, the user can view the calendar and any selected dates, but can't change the selection.
```
boolean
```
selected
The currently selected date or dates. Pass a date string for single-date selection, an array of date strings for multi-date selection, or a `Range` object for range selection. Update this value in your `onChange` handler to reflect the user's choice.
```
T
```
yearMonth
The year and month currently displayed in the calendar. Use this prop together with `onYearMonthChange` to control which month the user sees. When set, the calendar won't navigate on its own. You must update this value in response to `onYearMonthChange` to let the user browse months. Accepts either an object (`{ year, month }`) or a `YYYY-MM` string.
```
{year: Year; month: Month} | YearMonthString
```

Selected

The value type for date picker selections. Pass a single `DateString` for single-date mode, an array of `DateString` values for multi-date mode, or a `Range` object for range mode.

DateString | DateString[] | Range

DividerProps

Props for the Divider component, a visual separator used to distinguish adjacent sections of content.

direction
The direction the divider line runs. - `inline`: Draws a horizontal rule that separates stacked content. - `block`: Draws a vertical rule that separates side-by-side content.
```
'inline' | 'block'
```

EmailFieldProps

Props for the EmailField component, a text input optimized for email addresses. It inherits common input props (like `label`, `value`, `onChange`, and `error`) from `InputProps`, length validation from `MinMaxLengthProps`, and browser autofill hints from `AutocompleteProps`.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
maxLength
The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the `error` prop to communicate the constraint.
```
number
```
minLength
The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the `error` prop to communicate the constraint.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

AutocompleteSection

A section prefix that scopes autofill data to a specific area of the page. Use this when the same page contains multiple groups of fields that share the same autocomplete tokens, such as two separate shipping address forms. The value must follow the pattern `section-${name}`, for example `"section-shipping-1"`.

`section-${string}`

AutocompleteGroup

The contact information group the autocomplete data should be sourced from. - `shipping`: Autofill with the user's shipping address information. - `billing`: Autofill with the user's billing address information.

'shipping' | 'billing'

FormProps

Props for the Form component, a container that groups related input fields and manages submission and reset behavior through the save bar.

id
A unique identifier for the form. Use this when you need to reference the form from outside its tree, for example from a submit button that isn't a child of the form.
```
string
```
onReset
A callback that fires when the form is reset. This is triggered by the save bar's **Discard** action. Use it to revert your extension's state back to its last saved values. Return a `Promise` if you need to perform async cleanup.
```
() => void | Promise<void>
```
onSubmit
A callback that fires when the form is submitted. This is triggered by the save bar's **Save** action or by a submit button inside the form. Return a `Promise` if you need to perform async work (like a network request), and the Shopify admin will wait for it to resolve before treating the submission as complete.
```
() => void | Promise<void>
```

FunctionSettingsProps

Props for the FunctionSettings component, a form container designed for Shopify Function configuration experiences. It provides hooks for saving settings and handling server-side validation errors.

id
A unique identifier for the function settings form. Use this when you need to reference the form from elements outside its tree.
```
string
```
onError
A callback that fires when committing the saved changes to Shopify's servers fails. The `errors` array only contains errors caused by data your extension provided. Network errors and other issues outside your control aren't reported here. Use this callback to highlight the fields that caused the errors and display the error messages to the merchant.
```
(errors: FunctionSettingsError[]) => void
```
onSave
A callback that fires when the merchant saves their changes in the admin-rendered function settings experience. If you return a `Promise`, then the Shopify admin waits for it to resolve before committing changes to Shopify's servers. If the promise rejects, then the Shopify admin aborts the save and displays an error using the `message` property of the rejected value.
```
() => void | Promise<void>
```

FunctionSettingsError

Describes an error that occurred when committing function settings to Shopify's servers. These errors are scoped to data the extension provided and can be displayed directly to the merchant.

code
A machine-readable identifier for the category of error. These match GraphQL error codes as closely as possible. For example, the values returned by the `metafieldsSet` mutation. Learn more about the [MetafieldsSetUserErrorCode](/docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode) enum.
```
string
```
message
A human-readable, translated message describing the error. You can display this directly to the merchant.
```
string
```

HeadingProps

Props for the Heading component. The heading's semantic level is determined automatically by the nesting depth of HeadingGroup or Section ancestors; use the `size` prop to control its visual appearance independently.

id
A unique identifier for the heading.
```
string
```
size
The visual size of the heading, from `1` (largest) to `6` (smallest). This controls appearance only and doesn't set the semantic heading level. The actual heading level rendered for assistive technologies is determined automatically by the nesting depth of parent HeadingGroup or Section components.
```
Level
```

Level

A heading level from `1` (largest / most prominent) to `6` (smallest / least prominent). Controls visual size only. The semantic HTML heading level is determined by HeadingGroup or Section nesting.

1 | 2 | 3 | 4 | 5 | 6

HeadingGroupProps

Props for the HeadingGroup component. HeadingGroup doesn't accept any props of its own. It serves as a structural wrapper that increases the semantic heading level for any Heading components nested inside it. Each level of HeadingGroup nesting increments the heading level by one (for example, a Heading inside two HeadingGroup components renders as a level-3 heading).

IconProps

Props for the Icon component, which renders a Polaris icon by name. Inherits accessibility label support from `AccessibilityLabelProps`.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
id
A unique identifier for the icon.
```
string
```
name
The name of the icon to display.
```
IconName
```
size
The size of the icon. - `base`: Renders the icon at its standard size. - `fill`: Stretches the icon to fill the available space in its container while preserving its aspect ratio.
```
'base' | 'fill'
```
tone
The color of the icon. - `inherit`: Uses the color from the icon's parent, giving it a monochrome appearance that matches surrounding text. - `critical`: Applies a red, attention-grabbing color for error or destructive contexts.
```
'inherit' | 'critical'
```

ImageProps

Props for the Image component. Requires either `accessibilityLabel` or `alt` for alternative text, and either `source` or `src` for the image URL.

(ImageAccessibilityLabelProp | ImageAltProp) & (ImageSourceProp | ImageSrcProp) & ImageBaseProps

ImageAccessibilityLabelProp

Variant that uses `accessibilityLabel` for alternative text.

accessibilityLabel
Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load. An `alt` prop is available as an alias. Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
```
string
```
alt
The alternative text for the image. Typed as `never` on this variant because `accessibilityLabel` is already set. To use `alt` instead, omit `accessibilityLabel`.
```
never
```

ImageAltProp

Variant that uses `alt` for alternative text.

accessibilityLabel
The alternative text for the image. Typed as `never` on this variant because `alt` is already set. To use `accessibilityLabel` instead, omit `alt`.
```
never
```
alt
An alias for `accessibilityLabel`. Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load. Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
```
string
```

ImageSourceProp

Variant that uses `source` for the image URL.

source
The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported. A `src` prop is available as an alias.
```
string
```
src
The URL of the image to display. Typed as `never` on this variant because `source` is already set. To use `src` instead, omit `source`.
```
never
```

ImageSrcProp

Variant that uses `src` for the image URL.

source
The URL of the image to display. Typed as `never` on this variant because `src` is already set. To use `source` instead, omit `src`.
```
never
```
src
An alias for `source`. The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported.
```
string
```

ImageBaseProps

Base props shared by all Image variants.

accessibilityRole
The semantic role of the image for assistive technologies. - `decorative`: Marks the image as purely visual, so screen readers skip it entirely. Use this for images that don't convey meaningful content (like background patterns or visual flourishes).
id
A unique identifier for the image. Must be unique within the entire extension.
```
string
```
loading
Controls when the image starts loading. - `eager`: Loads the image immediately, regardless of whether it's visible in the viewport. - `lazy`: Defers loading until the image approaches the viewport, which can improve initial page performance.
```
'eager' | 'lazy'
```
onError
A callback that fires when the image fails to load (for example, due to a broken URL or network error). Use this to show a fallback or error state.
```
() => void
```
onLoad
A callback that fires when the image finishes loading successfully. Use this to trigger UI updates that depend on the image being ready (for example, removing a loading skeleton).
```
() => void
```

InlineStackProps

Props for the InlineStack component, a horizontal layout container that arranges children in a row along the inline axis. Inherits accessibility, sizing, padding, and gap props from shared utilities.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.
```
AccessibilityRole
```
blockAlignment
The alignment of children along the block (vertical) axis within the stack. Use this to control how children are vertically aligned in a horizontal stack layout.
```
CrossAxisAlignment
```
blockGap
The spacing between children along the block axis (top-to-bottom in horizontal writing modes). This is an alias for `rowGap`. When set to `true`, applies a default block gap appropriate for the component.
```
SpacingKeyword | boolean
```
blockSize
The block size (height in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size) property.
```
number | `${number}%`
```
columnGap
The spacing between columns (children placed along the inline axis). When set to `true`, applies a default column gap appropriate for the component. Learn more about the [column-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap) property.
```
SpacingKeyword | boolean
```
gap
The spacing between children in both axes. Accepts a single value for uniform spacing, or two values separated by a space for independent block-axis and inline-axis spacing (such as `"base small"`). When set to `true`, applies a default gap appropriate for the component. Learn more about the [gap](https://developer.mozilla.org/en-US/docs/Web/CSS/gap) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
id
A unique identifier for the element.
```
string
```
inlineAlignment
The alignment of children along the inline (horizontal) axis within the stack. Use this to control how children are horizontally distributed in a horizontal stack layout.
```
MainAxisAlignment
```
inlineGap
The spacing between children along the inline axis (left-to-right in horizontal writing modes). This is an alias for `columnGap`. When set to `true`, applies a default inline gap appropriate for the component.
```
SpacingKeyword | boolean
```
inlineSize
The inline size (width in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) property.
```
number | `${number}%`
```
maxBlockSize
The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [max-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) property.
```
number | `${number}%`
```
maxInlineSize
The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property.
```
number | `${number}%`
```
minBlockSize
The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [min-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) property.
```
number | `${number}%`
```
minInlineSize
The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property.
```
number | `${number}%`
```
padding
The padding on all edges of the element, using a shorthand syntax. You can specify one to four values following the [CSS shorthand convention](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box). When set to `true`, applies a default padding appropriate for the component.
```
MaybeAllBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlock
The padding on the block-start and block-end edges. When set to `true`, applies a default block padding appropriate for the component. Learn more about the [padding-block](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlockEnd
The padding on the block-end edge (the bottom edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-end) property.
```
SpacingKeyword | boolean
```
paddingBlockStart
The padding on the block-start edge (the top edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-start) property.
```
SpacingKeyword | boolean
```
paddingInline
The padding on the inline-start and inline-end edges. When set to `true`, applies a default inline padding appropriate for the component. Learn more about the [padding-inline](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingInlineEnd
The padding on the inline-end edge (the right edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-end) property.
```
SpacingKeyword | boolean
```
paddingInlineStart
The padding on the inline-start edge (the left edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-start) property.
```
SpacingKeyword | boolean
```
rowGap
The spacing between rows (children stacked along the block axis). When set to `true`, applies a default row gap appropriate for the component. Learn more about the [row-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap) property.
```
SpacingKeyword | boolean
```

InternalCustomerSegmentTemplateProps

category
```
CustomerSegmentTemplateCategory
```
createdOn
```
string
```

dependencies

{ standardMetafields?: "facts.birth_date"[]; customMetafields?: string[]; }

description
```
string | string[]
```
icon
```
CustomerSegmentTemplateIcon
```
query
```
string
```
queryToInsert
```
string
```
title
```
string
```

CustomerSegmentTemplateCategory

'firstTimeBuyers' | 'highValueCustomers' | 'reEngageCustomers' | 'abandonedCheckout' | 'purchaseBehaviour' | 'location'

CustomerSegmentTemplateIcon

'categoriesMajor' | 'firstVisitMajor' | 'heartMajor' | 'marketingMajor' | 'checkoutMajor' | 'ordersMajor' | 'locationMajor' | 'emailNewsletterMajor' | 'firstOrderMajor' | 'billingStatementDollarMajor' | 'diamondAlertMajor' | 'abandonedCartMajor' | 'calendarMajor' | 'productsMajor' | 'globeMajor' | 'flagMajor' | 'uploadMajor' | 'buyButtonMajor' | 'followUpEmailMajor' | 'confettiMajor' | 'walletMajor' | 'viewMajor' | 'personAddMajor' | 'languageMajor' | 'appsMajor' | 'categories' | 'eye-first' | 'heart' | 'target' | 'cart' | 'order' | 'location' | 'email-newsletter' | 'order-first' | 'receipt-dollar' | 'alert-diamond' | 'cart-abandoned' | 'calendar' | 'product' | 'globe' | 'flag' | 'upload' | 'button-press' | 'email-follow-up' | 'confetti' | 'wallet' | 'view' | 'person-add' | 'language' | 'apps'

InternalLocationListProps

locationGroups
An array of location groups.
```
LocationGroup[]
```
onCreateGroup
Callback when a new group is created. It receives the id of the new group as a parameter.
```
(id: string) => void
```
onDeleteGroup
Callback when a location group is deleted. It receives the id of the group as a parameter.
```
(id: string) => void
```
onMoveGroup
Callback when a location group is moved. It receives the old index and the new index as parameters.
```
(oldIndex: number, newIndex: number) => void
```
onMoveTag
Callback when a tag is moved from one group to another. It receives the id of the tag, the old group index, and the new group index as parameters.
```
(tagId: number, oldGroupIndex: number, newGroupIndex: number) => void
```
onRenameGroup
Callback when a location group is renamed. It receives the id of the group and the new name as parameters.
```
(id: string, name: string) => void
```

LocationGroup

id
A unique identifier for the location group.
```
string
```
label
The label for the location group.
```
string
```
locations
An array of locations within the group.
```
Location[]
```

Location

id
A unique identifier for the location.
```
string
```
name
The name of the location.
```
string
```

LinkProps

Props for the Link component, an interactive text element that navigates to a URL or triggers an action when pressed. Inherits accessibility label support from `AccessibilityLabelProps`.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
href
The URL to link to. If set, the link will navigate to the specified location after executing the `onClick` callback. Use this prop for standard navigation links within or outside the Shopify admin.
```
string
```
id
A unique identifier for the link. When not set, a globally unique value will be used instead.
```
string
```
lang
An alias for `language`. The language of the link's text content. Use this when the link text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
language
The language of the link's text content. Use this when the link text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
onClick
A callback that fires when the link is pressed. If `href` is set, the callback executes first and then the link navigates to the specified location.
```
() => void
```
onPress
An alias for `onClick`. A callback that fires when the link is pressed. If `href` is set, the callback executes first and then the link navigates to the specified location.
```
() => void
```
target
The browsing context for opening the linked URL. - `_blank`: Opens the link in a new tab or window. - `_self`: Opens the link in the current page (default behavior).
```
'_blank' | '_self'
```
to
An alias for `href`. If set, the link will navigate to the specified location after executing the `onClick` callback.
```
string
```
tone
The color of the link text. - `default`: Uses the standard link color to indicate an interactive element. - `inherit`: Takes the color value from its parent, giving the link a monochrome appearance. Pair this with another stylistic treatment, like an underline, to differentiate the link from normal text. - `critical`: Uses a critical (destructive) color to indicate a potentially dangerous action, such as deleting a resource.
```
'default' | 'inherit' | 'critical'
```

MoneyFieldProps

Props for the MoneyField component, a specialized input for entering monetary values. It extends standard input props with number constraints and autocomplete support for transaction amounts.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
currencyCode
The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code associated with the monetary value. This code is included in the `Money` object returned by `onChange`. For example, `'USD'` for US Dollars or `'EUR'` for Euros.
```
CurrencyCode
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
max
The highest decimal or integer to be accepted for the field. When using the stepper buttons, the value won't exceed this limit. If `step` would overshoot, then the value rounds down to `max`. A user can still type a number higher than `max` using the keyboard, so add appropriate validation with the `error` prop.
```
number
```
min
The lowest decimal or integer to be accepted for the field. When using the stepper buttons, the value won't go below this limit. If `step` would undershoot, then the value rounds up to `min`. A user can still type a number lower than `min` using the keyboard, so add appropriate validation with the `error` prop.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: number | Money) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: number | Money) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
step
The increment amount for the stepper buttons. This can be an integer or decimal (such as `0.01` for cents). Each press of the stepper button increases or decreases the value by this amount. If `max` or `min` is set, the final value always rounds to the boundary rather than overshooting.
```
number
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

CurrencyCode

The supported monetary currencies from [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).

'USD' | 'EUR' | 'GBP' | 'CAD' | 'AFN' | 'ALL' | 'DZD' | 'AOA' | 'ARS' | 'AMD' | 'AWG' | 'AUD' | 'BBD' | 'AZN' | 'BDT' | 'BSD' | 'BHD' | 'BIF' | 'BZD' | 'BMD' | 'BTN' | 'BAM' | 'BRL' | 'BOB' | 'BWP' | 'BND' | 'BGN' | 'MMK' | 'KHR' | 'CVE' | 'KYD' | 'XAF' | 'CLP' | 'CNY' | 'COP' | 'KMF' | 'CDF' | 'CRC' | 'HRK' | 'CZK' | 'DKK' | 'DOP' | 'XCD' | 'EGP' | 'ETB' | 'XPF' | 'FJD' | 'GMD' | 'GHS' | 'GTQ' | 'GYD' | 'GEL' | 'HTG' | 'HNL' | 'HKD' | 'HUF' | 'ISK' | 'INR' | 'IDR' | 'ILS' | 'IQD' | 'JMD' | 'JPY' | 'JEP' | 'JOD' | 'KZT' | 'KES' | 'KWD' | 'KGS' | 'LAK' | 'LVL' | 'LBP' | 'LSL' | 'LRD' | 'LTL' | 'MGA' | 'MKD' | 'MOP' | 'MWK' | 'MVR' | 'MXN' | 'MYR' | 'MUR' | 'MDL' | 'MAD' | 'MNT' | 'MZN' | 'NAD' | 'NPR' | 'ANG' | 'NZD' | 'NIO' | 'NGN' | 'NOK' | 'OMR' | 'PAB' | 'PKR' | 'PGK' | 'PYG' | 'PEN' | 'PHP' | 'PLN' | 'QAR' | 'RON' | 'RUB' | 'RWF' | 'WST' | 'SAR' | 'RSD' | 'SCR' | 'SGD' | 'SDG' | 'SYP' | 'ZAR' | 'KRW' | 'SSP' | 'SBD' | 'LKR' | 'SRD' | 'SZL' | 'SEK' | 'CHF' | 'TWD' | 'THB' | 'TZS' | 'TTD' | 'TND' | 'TRY' | 'TMT' | 'UGX' | 'UAH' | 'AED' | 'UYU' | 'UZS' | 'VUV' | 'VND' | 'XOF' | 'YER' | 'ZMW' | 'BYN' | 'BYR' | 'DJF' | 'ERN' | 'FKP' | 'GIP' | 'GNF' | 'IRR' | 'KID' | 'LYD' | 'MRU' | 'SLL' | 'SHP' | 'SOS' | 'STD' | 'STN' | 'TJS' | 'TOP' | 'VED' | 'VEF' | 'VES' | 'XXX'

Money

Represents a monetary value with an amount and currency code. Used as the value type for the MoneyField component.

amount
The monetary amount as a decimal number, such as `29.99`.
```
number
```
currencyCode
The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for the amount, such as `'USD'` or `'EUR'`.
```
CurrencyCode
```

NumberFieldProps

Props for the NumberField component, a text input for numeric values. Inherits standard input props, number constraints (min, max, step), autocomplete support, and field decoration props.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
inputMode
The type of virtual keyboard displayed on touch devices. - `decimal`: Shows a numeric keyboard with a decimal separator, suitable for values that may include fractional digits (for example, prices). - `numeric`: Shows a numeric keyboard without a decimal separator, suitable for whole numbers (for example, quantities).
```
'decimal' | 'numeric'
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
max
The highest decimal or integer to be accepted for the field. When using the stepper buttons, the value won't exceed this limit. If `step` would overshoot, then the value rounds down to `max`. A user can still type a number higher than `max` using the keyboard, so add appropriate validation with the `error` prop.
```
number
```
min
The lowest decimal or integer to be accepted for the field. When using the stepper buttons, the value won't go below this limit. If `step` would undershoot, then the value rounds up to `min`. A user can still type a number lower than `min` using the keyboard, so add appropriate validation with the `error` prop.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: number) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: number) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
step
The increment amount for the stepper buttons. This can be an integer or decimal (such as `0.01` for cents). Each press of the stepper button increases or decreases the value by this amount. If `max` or `min` is set, the final value always rounds to the boundary rather than overshooting.
```
number
```
suffix
A non-editable string displayed after the input area, such as `"@shopify.com"` or `"%"`. The suffix isn't included in the field's value. It might be hidden until the user focuses the field if an inline label occupies the same space.
```
string
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

ParagraphProps

Props for the Paragraph component, which renders a block of text as a distinct paragraph. Use Paragraph to structure your content into readable sections with appropriate spacing.

children
The content to render inside the paragraph. You can pass plain text or other inline components such as Text or Link.
```
any
```
fontSize
The font size, using the design-system size scale. Values range from `small-300` (smallest) through `base` (default) to `large-300` (largest). Prefer semantic heading components for page headings rather than manually increasing font size.
```
SizeScale
```
fontStyle
The font style. Use `italic` to emphasize a word or group of words, or to indicate a title, foreign phrase, or other conventionally italicized text. Learn more about the [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) property.
```
FontStyle
```
fontWeight
The weight (thickness) of the font. Use bolder weights to create visual emphasis or hierarchy. Values range from `light-300` (thinnest) through `base` (default) to `bold-300` (heaviest). Learn more about the [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) property.
```
FontWeight
```
id
A unique identifier for the element.
```
string
```
textOverflow
The behavior for signaling text that overflows its container to users. Currently supports only `ellipsis`, which truncates the text and appends an ellipsis (`…`). The element must also constrain its size (such as through `maxInlineSize`) for truncation to take effect. Learn more about the [text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow) property.
```
TextOverflow
```

SizeScale

A relative size scale used for typography sizing. Values range from smallest to largest: - `small-300`: The smallest available size. - `small-200`: Smaller than small-100. - `small-100`: Slightly below the base size. - `base`: The default size. - `large-100`: Slightly above the base size. - `large-200`: Larger than large-100. - `large-300`: The largest available size.

'small-300' | 'small-200' | 'small-100' | 'base' | 'large-100' | 'large-200' | 'large-300'

FontStyle

Controls the styling of the font's letter forms. - `italic`: Renders text in an italic typeface, typically used for emphasis. - `normal`: Renders text in the upright, default typeface. Learn more about the [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) property.

'italic' | 'normal'

FontWeight

Controls the thickness (weight) of the font. Values range from lightest to heaviest. Some values are convenience aliases. - `light-300`: The lightest available weight. - `light-200`: Lighter than light-100. - `light-100`: Slightly below base weight. - `light`: An alias for `light-100`. - `base`: The default font weight. - `normal`: An alias for `base`. - `bold`: An alias for `bold-100`. - `bold-100`: Slightly above base weight; used for emphasis. - `bold-200`: Heavier than bold-100. - `bold-300`: The heaviest available weight. Learn more about the [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) property.

'light-300' | 'light-200' | 'light-100' | 'light' | 'base' | 'normal' | 'bold' | 'bold-100' | 'bold-200' | 'bold-300'

TextOverflow

Controls how overflowing text content is signaled to the user when it doesn't fit within its container. - `ellipsis`: Truncates the text and displays an ellipsis (`…`) character at the point of truncation.

'ellipsis'

PasswordFieldProps

Props for the PasswordField component, a text input that masks its content for secure entry of sensitive values like passwords or PINs. It extends standard input props with min/max length constraints and autocomplete support for password managers.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
maxLength
The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the `error` prop to communicate the constraint.
```
number
```
minLength
The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the `error` prop to communicate the constraint.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

PressableProps

Props for the Pressable component, which combines the layout capabilities of Box with the interactive behavior of Link. Use Pressable when you need a custom interactive area that can navigate to a URL or respond to press events while supporting flexible layout and styling options.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.
```
AccessibilityRole
```
blockSize
The block size (height in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size) property.
```
number | `${number}%`
```
display
Whether the element is rendered and takes up space in the layout. - `auto`: The element is rendered normally and participates in layout. - `none`: The element isn't rendered at all and doesn't take up any space. Use this to conditionally hide content without removing it from the component tree.
```
'auto' | 'none'
```
href
The URL to link to. If set, the link will navigate to the specified location after executing the `onClick` callback. Use this prop for standard navigation links within or outside the Shopify admin.
```
string
```
id
A unique identifier for the link. When not set, a globally unique value will be used instead.
```
string
```
inlineSize
The inline size (width in horizontal writing modes) of the element. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) property.
```
number | `${number}%`
```
lang
An alias for `language`. The language of the link's text content. Use this when the link text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
language
The language of the link's text content. Use this when the link text is in a different language than the rest of the page so assistive technologies can invoke the correct pronunciation. Must be a valid [IANA language subtag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
```
string
```
maxBlockSize
The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [max-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) property.
```
number | `${number}%`
```
maxInlineSize
The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property.
```
number | `${number}%`
```
minBlockSize
The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's block size. Learn more about the [min-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) property.
```
number | `${number}%`
```
minInlineSize
The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value. - `number`: The size in pixels. - `` `${number}%` ``: The size as a percentage of the parent container's inline size. Learn more about the [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property.
```
number | `${number}%`
```
onClick
A callback that fires when the link is pressed. If `href` is set, the callback executes first and then the link navigates to the specified location.
```
() => void
```
onPress
An alias for `onClick`. A callback that fires when the link is pressed. If `href` is set, the callback executes first and then the link navigates to the specified location.
```
() => void
```
padding
The padding on all edges of the element, using a shorthand syntax. You can specify one to four values following the [CSS shorthand convention](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box). When set to `true`, applies a default padding appropriate for the component.
```
MaybeAllBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlock
The padding on the block-start and block-end edges. When set to `true`, applies a default block padding appropriate for the component. Learn more about the [padding-block](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingBlockEnd
The padding on the block-end edge (the bottom edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-end) property.
```
SpacingKeyword | boolean
```
paddingBlockStart
The padding on the block-start edge (the top edge in horizontal writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-block-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block-start) property.
```
SpacingKeyword | boolean
```
paddingInline
The padding on the inline-start and inline-end edges. When set to `true`, applies a default inline padding appropriate for the component. Learn more about the [padding-inline](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline) property.
```
MaybeTwoBoxEdgesShorthandProperty<SpacingKeyword | boolean>
```
paddingInlineEnd
The padding on the inline-end edge (the right edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-end](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-end) property.
```
SpacingKeyword | boolean
```
paddingInlineStart
The padding on the inline-start edge (the left edge in left-to-right writing modes). When set to `true`, applies a default padding appropriate for the component. Learn more about the [padding-inline-start](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline-start) property.
```
SpacingKeyword | boolean
```
target
The browsing context for opening the linked URL. - `_blank`: Opens the link in a new tab or window. - `_self`: Opens the link in the current page (default behavior).
```
'_blank' | '_self'
```
to
An alias for `href`. If set, the link will navigate to the specified location after executing the `onClick` callback.
```
string
```
tone
The color of the link text. - `default`: Uses the standard link color to indicate an interactive element. - `inherit`: Takes the color value from its parent, giving the link a monochrome appearance. Pair this with another stylistic treatment, like an underline, to differentiate the link from normal text. - `critical`: Uses a critical (destructive) color to indicate a potentially dangerous action, such as deleting a resource.
```
'default' | 'inherit' | 'critical'
```

ProgressIndicatorProps

Props for the ProgressIndicator component, which renders a visual cue (such as a spinner) to communicate that a process is underway. Use this component to reassure users that content is loading or an action is being processed.

accessibilityLabel
A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or `label` supplied won't be announced to screen readers.
```
string
```
id
A unique identifier for the element.
```
string
```
size
The size of the progress indicator. This prop is required and determines how large the indicator renders. Use smaller sizes for inline or compact placements, and larger sizes for prominent loading states.
```
SizeScale
```
tone
The color of the progress indicator. - `inherit`: Takes the color value from its parent, giving the progress indicator a monochrome appearance. This is useful when you want the indicator to blend with surrounding text or icons. - `default`: Uses the standard progress indicator color.
```
'inherit' | 'default'
```
variant
The visual style of the progress indicator. - `spinner`: Renders a circular spinning animation to indicate an indeterminate loading state.
```
'spinner'
```

SectionProps

Props for the Section component, which groups related content under an optional heading. Sections provide both visual and semantic structure, making it easier for users (and assistive technologies) to navigate through distinct areas of an extension.

accessibilityLabel
A label that describes the section for assistive technologies such as screen readers. When no `heading` prop is provided, then you **must** provide an `accessibilityLabel` so that assistive technologies can announce meaningful context about the section to users.
```
string
```
heading
A visible title displayed at the top of the section that describes its content. When provided, this heading also serves as the accessible label for the section unless `accessibilityLabel` is explicitly set.
```
string
```
padding
The padding on all edges of the section. - `base`: Applies padding that's appropriate for the context. This might result in no padding if Shopify determines that's the right design decision for a particular placement. - `none`: Removes all padding from the section. This is useful when child elements need to span to the section's edges (for example, a full-width image). Use Box or another layout component to restore padding for the remaining content.
```
'base' | 'none'
```

SelectProps

Props for the Select component, a form control that lets the user choose one value from a predefined list of options presented in a dropdown menu.

disabled
Whether the select is disabled. When `true`, the field can't be interacted with and appears in a dimmed state.
```
boolean
```
error
An error message to display beneath the field. When set, the field receives a specific stylistic treatment to communicate a problem that needs to be resolved immediately.
```
string
```
id
A unique identifier for the field. When no `id` is set, a globally unique value will be used instead.
```
string
```
label
The visible label displayed above the select field. This label is also used by assistive technologies to describe the field.
```
string
```
name
An identifier for the field that is unique within the nearest containing Form component. This value is used when submitting the form data.
```
string
```
onBlur
A callback that fires when the field loses focus. Use this to trigger validation or other side effects when the user moves away from the select.
```
() => void
```
onChange
A callback that fires whenever the selected option changes. The callback receives the string `value` of the newly selected option. This component is controlled, so you must store this value in state and reflect it back in the `value` prop.
```
(value: string) => void
```
onFocus
A callback that fires when the field receives focus. Use this to trigger side effects when the user interacts with the select.
```
() => void
```
options
The options a user can select from, provided as an array of `OptionDescription` or `OptionGroupDescription` objects. Each option requires a `label` and `value`.
```
(OptionDescription | OptionGroupDescription)[]
```
placeholder
A short hint that describes the expected value of the field. The placeholder is displayed when no `value` is set, giving the user guidance on what to select.
```
string
```
readOnly
Whether the field is read-only. When `true`, the current value can't be changed by the user but the field remains focusable and its value is still included in form submissions.
```
boolean
```
required
Whether the field requires a value. This adds semantic meaning to the field for assistive technologies, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, use the `error` prop.
```
boolean
```
value
The currently selected value. This should match the `value` property of one of the items in the `options` array. When not set, the value defaults to an empty string, which displays the `placeholder` text as the selected value.
```
string
```

OptionDescription

Describes a single selectable option when using the `options` prop on a Select component.

disabled
Whether this option is disabled. When `true`, the option appears dimmed and can't be selected by the user.
```
boolean
```
label
The text displayed to the user for this option.
```
string
```
value
The value that will be passed to the select's `onChange` callback when this option is selected.
```
string
```

OptionGroupDescription

Describes a group of related options when using the `options` prop on a Select component. Groups display a non-selectable heading label above their nested options.

disabled
Whether all options within this group are disabled. When `true`, none of the options in the group can be selected.
```
boolean
```
label
The visible label for this group of options. It's displayed as a non-selectable heading above the group's options.
```
string
```
options
The selectable options within this group. Each option requires a `label` and `value`.
```
OptionDescription[]
```

TextProps

Props for the Text component, an inline element for rendering and styling a run of text. Use Text to apply typographic treatments such as font weight, style, variant, and overflow behavior to a portion of content.

accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.
```
TextAccessibilityRole
```
fontStyle
The styling of the font's letter forms.
```
FontStyle
```
fontVariant
The font variant options that control the usage of alternate glyphs. You can pass a single value or an array of values to combine multiple variants.
```
FontVariantOptions | FontVariantOptions[]
```
fontWeight
The weight (or boldness) of the font. Use heavier weights to create visual emphasis or establish hierarchy in your content.
```
FontWeight
```
id
A unique identifier for the text element. When not set, a globally unique value is used instead.
```
string
```
textOverflow
The behavior for signaling hidden overflow content to users.
```
TextOverflow
```

TextAccessibilityRole

Accessibility roles that can be applied to the Text component to convey additional semantic meaning to assistive technologies. Each role maps to a corresponding HTML element or ARIA role in web-based hosts. - `address`: The text is contact information. - `deletion`: The text has been deleted; typically used for discounted prices. - `mark`: The text is marked or highlighted and relevant to the current action. - `emphasis`: The text has emphatic stress compared to surrounding text. - `offset`: The text is offset from normal prose (such as a foreign word or definition). - `strong`: The text indicates strong importance, seriousness, or urgency.

'address' | 'deletion' | 'mark' | 'emphasis' | 'offset' | 'strong'

FontVariantOptions

Font variant options that control the usage of alternate glyphs. - `numeric`: Enables alternate glyphs for numbers, fractions, and ordinal markers. - `all-small-caps`: Enables alternate glyphs for capital letters using small caps. - `none`: Disables all font-variant ligatures and resets other variants to their initial values. Learn more about the [font-variant](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant) property.

'numeric' | 'all-small-caps' | 'none'

TextAreaProps

Props for the TextArea component, a multi-line text input for entering longer-form content such as descriptions, comments, or notes. It extends standard input props with min/max length constraints and autocomplete support.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
maxLength
The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the `error` prop to communicate the constraint.
```
number
```
minLength
The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the `error` prop to communicate the constraint.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
rows
The number of visible text lines to display. This determines the initial height of the text area. Users can still enter more text than the visible lines allow.
```
number
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

TextFieldProps

Props for the TextField component, a single-line text input for entering short-form content such as names, emails, or search queries. It extends standard input props with min/max length constraints, autocomplete support, and a field decoration option (suffix).

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
maxLength
The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the `error` prop to communicate the constraint.
```
number
```
minLength
The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the `error` prop to communicate the constraint.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
suffix
A non-editable string displayed after the input area, such as `"@shopify.com"` or `"%"`. The suffix isn't included in the field's value. It might be hidden until the user focuses the field if an inline label occupies the same space.
```
string
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

URLFieldProps

Props for the URLField component, a text input optimized for entering URLs. It extends standard input props with min/max length constraints and autocomplete support for URL-related fields.

autocomplete
A hint to the browser about the expected content of the field, used to offer autofill suggestions. - `true`: The field supports autofill, but no specific content type is specified. - `false`: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes. - An `AutocompleteField` token (such as `'email'` or `'street-address'`): Tells the browser exactly what data to suggest for this field. Learn more about the supported [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
```
| AutocompleteField
    | `${AutocompleteSection} ${AutocompleteField}`
    | `${AutocompleteGroup} ${AutocompleteField}`
    | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}`
    | boolean
```
defaultValue
The initial value of the field when it isn't controlled by state. Use this instead of `value` when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through `onChange`.
```
string | string[]
```
disabled
Whether the field is disabled. When `true`, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
```
boolean
```
error
An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message. Pass `undefined` or omit this prop to clear the error state.
```
string
```
id
A unique identifier for the field.
```
string
```
label
The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
```
string
```
maxLength
The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the `error` prop to communicate the constraint.
```
number
```
minLength
The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the `error` prop to communicate the constraint.
```
number
```
name
An identifier for the field that is unique within the nearest containing Form component.
```
string
```
onBlur
A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
```
() => void
```
onChange
A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the `value` prop. This doesn't fire on every keystroke. Use `onInput` for real-time responses like clearing validation errors as the user types. Don't use `onInput` to control `value` because that can cause issues on lower-powered devices due to asynchronous rendering.
```
(value: string) => void
```
onFocus
A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
```
() => void
```
onInput
A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value. Use `onInput` for immediate responses like clearing validation errors as the user types. Don't use it to control the field's `value` prop. Use `onChange` for that instead.
```
(value: string) => void
```
placeholder
A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the `label` as it disappears after the user starts typing.
```
string
```
readOnly
Whether the field is read-only. Unlike `disabled`, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
```
boolean
```
required
Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the `error` prop.
```
boolean
```
value
The current value for the field. If omitted, then the field will be empty. You should update this value in response to the `onChange` callback.
```
T
```

RunnableExtension

Defines a runnable extension that executes logic and returns data without rendering UI. Your extension receives an API object with extension capabilities and returns a result. Use this for extensions that perform data operations, validation checks, or conditional logic like should-render targets.

ShouldRenderApi

The `ShouldRenderApi` object provides methods for controlling action extension visibility. Access the following properties on the `ShouldRenderApi` object to determine whether an associated action should appear based on the current context.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this data to determine whether the action extension should appear based on the current context.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ShouldRenderOutput

The output returned by `should-render` extension targets to control action visibility. Return `{display: true}` to show the action or `{display: false}` to hide it based on your conditional logic.

display
Whether to display the associated action extension. Set to `true` to show the action, `false` to hide it.
```
boolean
```

BlockExtensionApi

The `BlockExtensionApi` object provides methods for block extensions that render inline content on admin pages. Access the following properties on the `BlockExtensionApi` object to interact with the current context, navigate to other extensions, and display picker dialogs.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

Navigation

The `Navigation` object provides methods for navigating between extensions and admin pages.

navigate
Navigates to a specific extension or admin route. Currently supports navigating from a block extension to an action extension on the same resource page.
```
(url: string | URL) => void
```

CustomerSegmentTemplateApi

The `CustomerSegmentTemplateApi` object provides methods for creating customer segment templates. Access the following properties on the `CustomerSegmentTemplateApi` object to build templates with translated content.

__enabledFeatures
```
string[]
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating template content into the merchant's language.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

CustomerSegmentTemplateComponent

The specialized set of components available for customer segment template extensions. This includes only the CustomerSegmentTemplate component used for defining segment query templates in the customer segmentation editor.

AnyComponentBuilder<
  Pick<
    Components,
    'CustomerSegmentTemplate' | 'InternalCustomerSegmentTemplate'
  >
>

DiscountFunctionSettingsApi

The `DiscountFunctionSettingsApi` object provides methods for configuring discount functions. Access the following properties on the `DiscountFunctionSettingsApi` object to manage function settings and metafields.

applyMetafieldChange
Updates or removes [metafields](/docs/apps/build/metafields) that store discount function configuration. Use this to save merchant settings for your discount function.
```
ApplyMetafieldChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The discount being configured and its associated [metafields](/docs/apps/build/metafields) storing function settings.
```
DiscountFunctionSettingsData
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ApplyMetafieldChange

A function that applies metafield changes to discount function settings. Call this function with an update or removal operation, then await the Promise to receive a result indicating success or failure. Use the result to provide feedback or handle errors in your settings interface.

change
```
MetafieldChange
```

returns

Promise<MetafieldChangeResult>

MetafieldChange

A metafield change operation that can either update or remove a metafield. Pass this to `applyMetafieldChange` to modify discount settings stored in metafields.

MetafieldUpdateChange | MetafieldRemoveChange

MetafieldUpdateChange

A metafield update or creation operation. Use this to set or modify metafield values that store discount function configuration data.

key
The unique key identifying the metafield within its namespace. Use descriptive keys that indicate the setting's purpose (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields. When omitted, a default namespace is assigned. Use consistent namespaces to group related settings.
```
string
```
type
Identifies this as an update operation. Always set to `'updateMetafield'` for updates.
```
'updateMetafield'
```
value
The metafield value to store. Can be a string or number depending on your configuration needs.
```
string | number
```
valueType
The [data type](/docs/apps/build/metafields/list-of-data-types) that defines how the value is formatted and validated. When omitted, preserves the existing type for updates or uses a default for new metafields. Choose a type that matches your value format.
```
SupportedDefinitionType
```

SupportedDefinitionType

The supported [metafield definition types](/docs/apps/build/metafields/list-of-data-types) for storing extension configuration data. Use these types to specify how metafield values should be formatted, validated, and displayed. Types prefixed with `list.` store arrays of values, while other types store single values. Choose a type that matches your data format (for example, use `'number_integer'` for whole numbers, `'single_line_text_field'` for short text, or `'json'` for complex structured data).

'boolean' | 'collection_reference' | 'color' | 'date' | 'date_time' | 'dimension' | 'file_reference' | 'json' | 'metaobject_reference' | 'mixed_reference' | 'money' | 'multi_line_text_field' | 'number_decimal' | 'number_integer' | 'page_reference' | 'product_reference' | 'rating' | 'rich_text_field' | 'single_line_text_field' | 'product_taxonomy_value_reference' | 'url' | 'variant_reference' | 'volume' | 'weight' | 'list.collection_reference' | 'list.color' | 'list.date' | 'list.date_time' | 'list.dimension' | 'list.file_reference' | 'list.metaobject_reference' | 'list.mixed_reference' | 'list.number_decimal' | 'list.number_integer' | 'list.page_reference' | 'list.product_reference' | 'list.rating' | 'list.single_line_text_field' | 'list.url' | 'list.variant_reference' | 'list.volume' | 'list.weight'

MetafieldRemoveChange

A metafield removal operation. Use this to delete metafields that are no longer needed for your discount configuration.

key
The unique key of the metafield to remove. Must match the key used when the metafield was created.
```
string
```
namespace
The namespace containing the metafield to remove. Required to ensure the correct metafield is targeted, as the same key can exist in different namespaces.
```
string
```
type
Identifies this as a removal operation. Always set to `'removeMetafield'` for deletions.
```
'removeMetafield'
```

MetafieldChangeResult

The result returned after attempting to change a metafield. Check the `type` property to determine if the operation succeeded (`'success'`) or failed (`'error'`), then handle the result appropriately in your extension.

MetafieldChangeSuccess | MetafieldChangeResultError

MetafieldChangeSuccess

A successful metafield change operation result. The metafield was updated or removed as requested and the changes are now saved.

type
Indicates the operation succeeded. When this value is `'success'`, the metafield change was applied successfully.
```
'success'
```

MetafieldChangeResultError

A failed metafield change operation result. Use the error message to understand what went wrong and fix the issue, such as validation errors, permission problems, or invalid metafield types.

message
A human-readable error message explaining why the operation failed. Use this to debug issues or display feedback to merchants.
```
string
```
type
Indicates the operation failed. Check this value to determine if you need to handle an error.
```
'error'
```

DiscountFunctionSettingsData

The `data` object exposed to discount function settings extensions in the `admin.discount-details.function-settings.render` target. Use this to access the current discount configuration and populate your settings interface with existing values.

id
The discount being configured by the merchant. Use this ID to associate configuration changes with the correct discount.
```
Discount
```
metafields
An array of [metafields](/docs/apps/build/metafields) that store the discount function's configuration values. Use these metafields to populate your settings UI with the current discount configuration and display existing settings to merchants.
```
Metafield[]
```

Discount

A discount that is being configured by the merchant. Use this to access the discount's unique identifier when saving configuration changes or making GraphQL queries.

id
The discount's unique global identifier (GID) in the [GraphQL Admin API](/docs/api/admin-graphql) format (for example, `gid://shopify/DiscountAutomaticApp/123`). Use this ID to associate settings with the correct discount or query discount data.
```
string
```

Metafield

A [metafield](/docs/apps/build/metafields) that stores discount function configuration data. Use metafields to persist settings that control how your discount function behaves, such as discount thresholds, eligibility rules, or custom discount logic parameters.

description
A human-readable description explaining the metafield's purpose and how it affects discount behavior. Use this to document your settings for other developers.
```
string
```
id
The unique global identifier (GID) for this metafield. Use this ID to reference the metafield in GraphQL queries or updates.
```
string
```
key
The unique key identifying this metafield within its namespace. This key determines how you access the metafield value (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields together. All metafields for a discount should use a consistent namespace to group related settings.
```
string
```
type
The metafield [definition type](/docs/apps/build/metafields/list-of-data-types) that specifies the value format and validation rules. Use this to determine how to parse and display the value.
```
string
```
value
The metafield value stored as a string. Parse this value according to the metafield type to use it in your settings UI.
```
string
```

PrintActionExtensionApi

The `PrintActionExtensionApi` object provides methods for print action extensions that generate custom printable documents. Access the following properties on the `PrintActionExtensionApi` object to access selected resources and display picker dialogs for print configuration.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items to include in the print document, such as selected orders or products.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose print settings or document configurations.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose additional resources to include in the print document.
```
ResourcePickerApi
```

PurchaseOptionsCardConfigurationApi

The `PurchaseOptionsCardConfigurationApi` object provides methods for action extensions that interact with purchase options and selling plans. Access the following properties on the `PurchaseOptionsCardConfigurationApi` object to work with selected products and their associated subscription configurations.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
close
Closes the extension modal. Use this when your extension completes its task or the merchant wants to exit. Equivalent to clicking the close button in the overlay corner.
```
() => void
```
data
Selected purchase option data including product and selling plan identifiers.
```
{ selected: { id: string; sellingPlanId?: string; }[]; }
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ProductVariantDetailsConfigurationApi

The `ProductVariantDetailsConfigurationApi` object provides methods for configuring product variant bundles and relationships. Access the following properties on the `ProductVariantDetailsConfigurationApi` object to build variant configuration interfaces.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
Variant configuration data including the current variant, selected items, and app URLs. Use this to access the variant being configured and build your configuration interface.
```
Data & { variant: ProductVariant; app: { launchUrl: string; applicationUrl: string; }; }
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ProductVariant

A product variant configuration.

barcode
The barcode value for the variant (for example, UPC, ISBN, or other barcode standards).
```
string
```
compareAtPrice
The compare-at (original) price as a decimal string, shown for sale pricing (for example, `"29.99"`).
```
string
```
displayName
The display name showing variant options (for example, "Blue / M").
```
string
```
id
The variant's unique global identifier (GID).
```
string
```
price
The variant's price as a decimal string (for example, `"19.99"`).
```
string
```
productVariantComponents
An array of component variants that make up this bundle variant. Each component represents a variant included in the bundle configuration.
```
ProductVariantComponent[]
```
selectedOptions
The selected option values that define this variant (for example, `[{name: "Color", value: "Blue"}, {name: "Size", value: "M"}]`).
```
{ name: string; value: string; }[]
```
sku
The stock keeping unit (SKU) identifier for inventory tracking.
```
string
```
taxable
Whether the variant is taxable. When `true`, taxes are calculated for this variant at checkout.
```
boolean
```
taxCode
The tax code used for calculating taxes (for example, HS codes or other jurisdiction-specific codes).
```
string
```
title
The variant's full title including option values (for example, "Blue T-Shirt - Size M").
```
string
```
weight
The variant's weight as a number. Use with weight units to calculate shipping costs.
```
number
```

ProductVariantComponent

A component variant that is part of a bundle variant. Represents an individual variant included in a bundle configuration.

displayName
The display name showing variant options (for example, "Blue / M").
```
string
```
id
The component variant's unique global identifier (GID).
```
string
```
image
The image displayed for this component variant with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces.
```
{
    id?: string | null;
    url?: string | null;
    altText?: string | null;
  } | null
```
productVariantUrl
The admin URL for this component variant. Use this to create links to the variant's details page in the admin.
```
string
```
selectedOptions
The selected option values that define this component variant (for example, `[{name: "Color", value: "Blue"}, {name: "Size", value: "M"}]`).
```
{ name: string; value: string; }[]
```
sku
The stock keeping unit (SKU) identifier for inventory tracking, or undefined if not set.
```
string
```
title
The variant's full title including product and option values.
```
string
```

OrderRoutingRuleApi

The `OrderRoutingRuleApi` object provides methods for configuring order routing rules. Access the following properties on the `OrderRoutingRuleApi` object to manage rule settings and metafields.

applyMetafieldsChange
Updates or removes [metafields](/docs/apps/build/metafields) that store order routing rule configuration.
```
ApplyMetafieldsChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The order routing rule being configured, including its metadata and associated [metafields](/docs/apps/build/metafields).
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ApplyMetafieldsChange

A function that applies metafield changes to order routing rule settings. Call this function with one or more change operations to update or remove metafields in batch. Use batch operations to apply multiple configuration changes efficiently.

changes
```
MetafieldsChange[]
```

returns

void

MetafieldsChange

One or more metafield change operations to apply to order routing rule settings. Can be a single change or an array of changes for batch operations. Use arrays to apply multiple changes at once.

MetafieldUpdateChange | MetafieldRemoveChange | MetafieldUpdateChange[] | MetafieldRemoveChange[]

ValidationSettingsApi

The `ValidationSettingsApi` object provides methods for configuring cart and checkout validation functions. Access the following properties on the `ValidationSettingsApi` object to manage validation settings and metafields.

applyMetafieldChange
Updates or removes [metafields](/docs/apps/build/metafields) that store validation function configuration. Use this to save merchant settings for your validation function.
```
ApplyMetafieldChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The validation being configured and its associated [metafields](/docs/apps/build/metafields) storing function settings.
```
ValidationData
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ValidationData

The `data` object exposed to validation settings extensions in the `admin.settings.validation.render` target. Use this to access the current validation configuration and populate your settings interface with existing values.

shopifyFunction
The [Shopify Function](/docs/apps/build/functions) that implements the validation logic. Use this ID to associate configuration changes with the correct function.
```
ShopifyFunction
```
validation
The validation configuration containing the validation ID and metafields. Present when editing an existing validation, absent when creating a new validation. Use the presence of this value to determine if you're in create or edit mode.
```
Validation
```

ShopifyFunction

A [Shopify Function](/docs/apps/build/functions) that implements cart and checkout validation logic. This identifies which function the settings interface is configuring.

id
The [Shopify Function's](/docs/apps/build/functions) unique global identifier (GID). Use this ID to associate settings changes with the correct function.
```
string
```

Validation

A validation configuration that exists and is active in the shop. Use this object to access the validation's current settings and metafields when merchants edit an existing validation.

id
The validation's unique global identifier (GID). Use this ID to reference the validation in GraphQL operations or when saving updated settings.
```
string
```
metafields
An array of [metafields](/docs/apps/build/metafields) that store the validation's configuration values. Use these metafields to populate your settings UI with the current validation configuration.
```
Metafield[]
```

Examples

import React, {useState} from 'react';

import {

reactExtension,

useApi,

Button,

Text,

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

const SelectBundleComponents = () => {

const {data, resourcePicker} = useApi<'admin.product-details.configuration.render'>();

const [selected, setSelected] = useState<any[]>([]);

const parentProductId = data.selected[0]?.id;

const handleSelectComponents = async () => {

const componentProducts = await resourcePicker({

type: 'product',

multiple: 5,

action: 'select',

filter: {

draft: false,

archived: false,

});

if (componentProducts) {

setSelected(componentProducts);

await fetch('/api/bundles/configure', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({

bundleProductId: parentProductId,

components: componentProducts.map((p) => ({

productId: p.id,

quantity: 1,

})),

}),

});

}

};

return (

{selected.length > 0 && <Text>{selected.length} components selected</Text>}

</>

);

};

export default reactExtension(

'admin.product-details.configuration.render',

() => <SelectBundleComponents />,

);

Examples

Select bundle components

Description

Open the product [resource picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) to select up to five components for a [bundle](/docs/apps/build/product-merchandising/bundles). This example filters out draft and archived products, saves the bundle configuration to your backend, and tracks the selection count.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  Button,
  Text,
} from '@shopify/ui-extensions-react/admin';

const SelectBundleComponents = () => {
  const {data, resourcePicker} = useApi<'admin.product-details.configuration.render'>();
  const [selected, setSelected] = useState<any[]>([]);

  const parentProductId = data.selected[0]?.id;

  const handleSelectComponents = async () => {
    const componentProducts = await resourcePicker({
      type: 'product',
      multiple: 5,
      action: 'select',
      filter: {
        draft: false,
        archived: false,
      },
    });

    if (componentProducts) {
      setSelected(componentProducts);

      await fetch('/api/bundles/configure', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          bundleProductId: parentProductId,
          components: componentProducts.map((p) => ({
            productId: p.id,
            quantity: 1,
          })),
        }),
      });
    }
  };

  return (
    <>
      <Button title="Select Components" onPress={handleSelectComponents} />
      {selected.length > 0 && <Text>{selected.length} components selected</Text>}
    </>
  );
};

export default reactExtension(
  'admin.product-details.configuration.render',
  () => <SelectBundleComponents />,
);

TS

import {extension, Button, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.configuration.render',
  (root, api) => {
    const {data, resourcePicker} = api;

    let selectedCount = 0;
    let countText;

    const parentProductId = data.selected[0]?.id;

    const selectButton = root.createComponent(Button, {
      title: 'Select Components',
      onPress: async () => {
        const componentProducts = await resourcePicker({
          type: 'product',
          multiple: 5,
          action: 'select',
          filter: {
            draft: false,
            archived: false,
          },
        });

        if (componentProducts) {
          selectedCount = componentProducts.length;

          await fetch('/api/bundles/configure', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({
              bundleProductId: parentProductId,
              components: componentProducts.map((p) => ({
                productId: p.id,
                quantity: 1,
              })),
            }),
          });

          if (countText) {
            root.removeChild(countText);
          }

          countText = root.createComponent(
            Text,
            {},
            `${selectedCount} components selected`,
          );
          root.appendChild(countText);
        }
      },
    });

    root.appendChild(selectButton);
  },
);

Load bundle configuration

Description

Query a product's [bundle](/docs/apps/build/product-merchandising/bundles) metafield and parse the JSON components array. This example fetches bundle data using the [GraphQL Admin API](/docs/api/admin-graphql/), parses the stored configuration, and displays the component count.

React

import React, {useState, useEffect} from 'react';
import {
  reactExtension,
  useApi,
  Text,
} from '@shopify/ui-extensions-react/admin';

const LoadBundleConfig = () => {
  const {data, query} = useApi<'admin.product-details.configuration.render'>();
  const [components, setComponents] = useState<any[]>([]);

  useEffect(() => {
    const loadConfig = async () => {
      const productId = data.selected[0]?.id;

      const {data: bundleData} = await query(
        `query GetBundleComponents($id: ID!) {
          product(id: $id) {
            id
            title
            metafield(namespace: "bundle", key: "components") {
              value
            }
          }
        }`,
        {variables: {id: productId}},
      );

      const comps = bundleData.product.metafield
        ? JSON.parse(bundleData.product.metafield.value)
        : [];

      setComponents(comps);
    };

    loadConfig();
  }, [data, query]);

  return (
    <>
      <Text>{components.length} components configured</Text>
      {components.map((comp, i) => (
        <Text key={i}>Component {i + 1}</Text>
      ))}
    </>
  );
};

export default reactExtension(
  'admin.product-details.configuration.render',
  () => <LoadBundleConfig />,
);

TS

import {extension, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.configuration.render',
  (root, api) => {
    const {data, query} = api;

    const loadConfig = async () => {
      const productId = data.selected[0]?.id;

      const {data: bundleData} = await query(
        `query GetBundleComponents($id: ID!) {
          product(id: $id) {
            id
            title
            metafield(namespace: "bundle", key: "components") {
              value
            }
          }
        }`,
        {variables: {id: productId}},
      );

      const components = bundleData.product.metafield
        ? JSON.parse(bundleData.product.metafield.value)
        : [];

      const summaryText = root.createComponent(
        Text,
        {},
        `${components.length} components configured`,
      );
      root.appendChild(summaryText);

      components.forEach((comp, i) => {
        const compText = root.createComponent(Text, {}, `Component ${i + 1}`);
        root.appendChild(compText);
      });
    };

    loadConfig();
  },
);

Update bundle metadata

Description

Save bundle display name and metadata using GraphQL mutations. This example uses a [text field](/docs/api/admin-extensions/2025-07/ui-components/forms/textfield) for input, calls `productUpdate` to save the metafield, and shows confirmation feedback.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  TextField,
  Button,
  Text,
  BlockStack,
} from '@shopify/ui-extensions-react/admin';

const UpdateBundleMetadata = () => {
  const {data, query} = useApi<'admin.product-details.configuration.render'>();
  const [bundleName, setBundleName] = useState('');
  const [saved, setSaved] = useState(false);

  const productId = data.selected[0]?.id;

  const handleSave = async () => {
    await query(
      `mutation UpdateBundleName($id: ID!, $metafields: [MetafieldsSetInput!]!) {
        productUpdate(input: {id: $id, metafields: $metafields}) {
          product {
            id
          }
        }
      }`,
      {
        variables: {
          id: productId,
          metafields: [
            {
              namespace: 'bundle',
              key: 'display_name',
              value: bundleName,
              type: 'single_line_text_field',
            },
          ],
        },
      },
    );

    setSaved(true);
  };

  return (
    <BlockStack>
      <Text>Product ID: {productId}</Text>
      <TextField
        label="Bundle display name"
        value={bundleName}
        onChange={setBundleName}
      />
      <Button title="Save Bundle Metadata" onPress={handleSave} />
      {saved && <Text>Bundle metadata saved</Text>}
    </BlockStack>
  );
};

export default reactExtension(
  'admin.product-details.configuration.render',
  () => <UpdateBundleMetadata />,
);

TS

import {extension, TextField, Button, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.configuration.render',
  (root, api) => {
    const {data, query} = api;

    let bundleName = '';
    let saveText;

    const productId = data.selected[0]?.id;

    const stack = root.createComponent(BlockStack);

    const productText = root.createComponent(Text, {}, `Product ID: ${productId}`);

    const nameField = root.createComponent(TextField, {
      label: 'Bundle display name',
      value: bundleName,
      onChange: (value) => {
        bundleName = value;
      },
    });

    const saveButton = root.createComponent(Button, {
      title: 'Save Bundle Metadata',
      onPress: async () => {
        await query(
          `mutation UpdateBundleName($id: ID!, $metafields: [MetafieldsSetInput!]!) {
            productUpdate(input: {id: $id, metafields: $metafields}) {
              product {
                id
              }
            }
          }`,
          {
            variables: {
              id: productId,
              metafields: [
                {
                  namespace: 'bundle',
                  key: 'display_name',
                  value: bundleName,
                  type: 'single_line_text_field',
                },
              ],
            },
          },
        );

        if (saveText) {
          stack.removeChild(saveText);
        }

        saveText = root.createComponent(Text, {}, 'Bundle metadata saved');
        stack.appendChild(saveText);
      },
    });

    stack.appendChild(productText);
    stack.appendChild(nameField);
    stack.appendChild(saveButton);

    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Design for products with multiple variants: Products in api.data.selected might have multiple variants. Design your bundle configuration to either apply to all variants or allow variant-level configuration.
Use the Resource Picker to select components: Use the Resource Picker API to let merchants select component products for bundle configurations.
Implement cart transforms to enforce bundles: Configuration only defines relationships in admin. Use Shopify Functions cart transforms to actually bundle products at checkout based on your saved configuration.

Anchor to LimitationsLimitations

Configuration extensions only render in the admin. They don't affect storefront display or checkout behavior. You must implement storefront and checkout logic separately.
Bundles aren't enforced automatically. Saving configuration doesn't automatically create bundles. You must implement cart transforms or other mechanisms to enforce bundling at purchase time.
Your extension can't directly modify product properties. The API is read-only for product data. Use GraphQL mutations like productUpdate to update products if needed.

Was this page helpful?