Choose a version:

Settings

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);
  },
);

Define merchant settings

Description

You can define settings that merchants can edit within the checkout editor. See [settings](/docs/api/checkout-ui-extensions/configuration#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"