# Settings The API for interacting with merchant settings. ### Accessing merchant settings ```jsx 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} />; } ``` ```js 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); }, ); ``` ## StandardApi The base API object provided to `purchase` extension targets. ### Docs_Standard_SettingsApi ### settings value: `StatefulRemoteSubscribable<ExtensionSettings>` The settings matching the settings definition written in the [`shopify.extension.toml`](/docs/api/checkout-ui-extensions/configuration) file. Refer to [settings examples](/docs/api/checkout-ui-extensions/apis/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. ### ExtensionSettings The merchant-defined setting values for the extension. Record< string, string | number | boolean | undefined > ## Related - [Targets](/docs/api/checkout-ui-extensions/targets) - [Components](/docs/api/checkout-ui-extensions/components) - [Configuration](/docs/api/checkout-ui-extensions/configuration) - [Tutorials](/apps/checkout) ## Examples The API for interacting with merchant settings. ### 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. ### Define merchant settings ```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" ``` ## useSettings Returns the setting values defined by the merchant for the extension. ### UseSettingsGeneratedType Returns the setting values defined by the merchant for the extension. #### Returns: Partial<Settings extends ExtensionSettings> export function useSettings< Settings extends ExtensionSettings, >(): Partial<Settings> { const settings = useSubscription(useApi().settings); return settings as Settings; } ### ExtensionSettings The merchant-defined setting values for the extension. Record< string, string | number | boolean | undefined > ## Related - [Targets](/docs/api/checkout-ui-extensions/targets) - [Components](/docs/api/checkout-ui-extensions/components) - [Configuration](/docs/api/checkout-ui-extensions/configuration) - [Tutorials](/apps/checkout) ## Examples The API for interacting with merchant settings. ### 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. ### Define merchant settings ```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" ```