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:

Settings API

The API for interacting with merchant settings.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to settings settings StatefulRemoteSubscribable<> required: The settings matching the settings definition written in the shopify.extension.toml file.

Refer to settings examples for more information.

Note
When an extension is being installed in the editor, the settings will be empty until a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.
Note: When an extension is being installed in the editor, the settings will be empty until a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.

Anchor to useSettings
useSettings()

Returns the setting values defined by the merchant for the extension.

Anchor to useSettings-returnsReturns

Partial<Settings extends >

Examples

import {

reactExtension,

Banner,

useSettings,

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

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {banner_title} = useSettings();

return <Banner title={banner_title} />;

}

Examples

Accessing merchant settings

Description

You can retrieve settings values within your extension. In React, the `useSettings()` hook re-renders your extension with the latest values. In JavaScript, subscribe to changes and update your UI directly.

React

import {
  reactExtension,
  Banner,
  useSettings,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {banner_title} = useSettings();
  return <Banner title={banner_title} />;
}

JavaScript

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, {settings}) => {
    const banner = root.createComponent(Banner, {
      title: settings.current.banner_title,
    });

    // When the merchant updates the banner title in the checkout editor, re-render the banner
    settings.subscribe((newSettings) => {
      banner.updateProps({
        title: newSettings.banner_title,
      });
    });

    root.appendChild(banner);
  },
);

Description

You can define settings that merchants can edit within the checkout and accounts editor. See [settings](/docs/apps/build/app-extensions/configure-app-extensions#settings-definition) for more information on how to define these.

shopify.extension.toml

api_version = "2023-07"

[[extensions]]
name = "My checkout extension"
handle = "checkout-ui"
type = "ui_extension"

  [[extensions.targeting]]
  target = "purchase.checkout.block.render"
  module = "./Checkout.jsx"

  [extensions.settings]
    [[extensions.settings.fields]]
    key = "banner_title"
    type = "single_line_text_field"
    name = "Banner title"
    description = "Enter a title for the banner."
    [[extensions.settings.fields.validations]]
    name = "min"
    value = "5"
    [[extensions.settings.fields.validations]]
    name = "max"
    value = "20"

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?

Anchor to StandardApiStandardApi

ExtensionSettings

Anchor to useSettingsuseSettings()

Anchor to useSettings-returnsReturns

Anchor to RelatedRelated

Anchor to useSettings
useSettings()