Skip to main content
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.

FunctionSettings

Requires the Discount Function Settings API, Validation Settings API, or Order Routing Rule API.

The FunctionSettings component configures metafield settings for Shopify Functions. Use FunctionSettings to create configuration interfaces that allow merchants to customize function behavior through structured input fields and controls.

This component provides a standardized layout for settings forms and integrates with the native save bar to handle form submission. For general form submission, use Form.

Support
Targets (46)

Supported targets

Anchor to PropertiesProperties

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.

Anchor to id
id
string

A unique identifier for the function settings form. Use this when you need to reference the form from elements outside its tree.

Anchor to onError
onError
(errors: []) => void

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.

Anchor to onSave
onSave
() => void | Promise<void>

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.

Anchor to ExamplesExamples

Anchor to Configure function validation settingsConfigure function validation settings

Build a settings page for a Shopify Function that saves configuration as metafields. This example uses FunctionSettings with applyMetafieldsChange to save a validation rule name entered in a TextField.

Configure function validation settings

Build a settings page for a [Shopify Function](/docs/api/functions) that saves configuration as metafields. This example uses `FunctionSettings` with `applyMetafieldsChange` to save a validation rule name entered in a [TextField](/docs/api/admin-extensions/2025-07/ui-components/forms/textfield).

Configure function validation settings

import {useState} from 'react';
import {reactExtension, useApi, FunctionSettings, TextField, Section} from '@shopify/ui-extensions-react/admin';

export default reactExtension(
'admin.settings.validation.render',
async (api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};
return <App settings={initialSettings} />;
},
);

function App({settings}) {
const [name, setName] = useState(settings.name || '');
const [error, setError] = useState();
const {applyMetafieldsChange} = useApi();

return (
<FunctionSettings onError={(errors) => setError(errors[0]?.message)}>
<Section heading="Validation settings">
<TextField
label="Rule name"
name="name"
value={name}
error={error}
onChange={(value) => {
setName(value);
setError(undefined);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'name',
value,
valueType: 'single_line_text_field',
});
}}
/>
</Section>
</FunctionSettings>
);
}
import {extension, FunctionSettings, TextField, Section} from '@shopify/ui-extensions/admin';

export default extension(
'admin.settings.validation.render',
async (root, api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};

const nameField = root.createComponent(TextField, {
value: initialSettings.name || '',
label: 'Rule name',
name: 'name',
onChange(value) {
nameField.updateProps({value, error: undefined});
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'name',
value,
valueType: 'single_line_text_field',
});
},
});

const section = root.createComponent(Section, {
heading: 'Validation settings',
});

const settings = root.createComponent(FunctionSettings, {
onError(errors) {
nameField.updateProps({error: errors[0]?.message});
},
});

section.appendChild(nameField);
settings.appendChild(section);
root.appendChild(settings);
},
);

Anchor to Manage multiple metafield settingsManage multiple metafield settings

Collect multiple metafield values in a single settings form using NumberField and TextField components. This example manages minimum quantity, maximum quantity, and a custom error message, writing each change to its own metafield key through applyMetafieldsChange.

Manage multiple metafield settings

import {useState} from 'react';
import {reactExtension, useApi, FunctionSettings, TextField, NumberField, Section} from '@shopify/ui-extensions-react/admin';

export default reactExtension(
'admin.settings.validation.render',
async (api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};
return <App settings={initialSettings} />;
},
);

function App({settings}) {
const [min, setMin] = useState(settings.minQuantity || 1);
const [max, setMax] = useState(settings.maxQuantity || 100);
const [message, setMessage] = useState(settings.errorMessage || '');
const [error, setError] = useState();
const {applyMetafieldsChange} = useApi();

return (
<FunctionSettings onError={(errors) => setError(errors[0]?.message)}>
<Section heading="Quantity limits">
<NumberField
label="Minimum order quantity"
name="minQuantity"
min={1}
value={min}
error={error}
onChange={(value) => {
setMin(value);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'min_quantity',
value: String(value),
valueType: 'number_integer',
});
}}
/>
<NumberField
label="Maximum order quantity"
name="maxQuantity"
min={1}
value={max}
onChange={(value) => {
setMax(value);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'max_quantity',
value: String(value),
valueType: 'number_integer',
});
}}
/>
<TextField
label="Error message shown to customers"
name="errorMessage"
value={message}
onChange={(value) => {
setMessage(value);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'error_message',
value,
valueType: 'single_line_text_field',
});
}}
/>
</Section>
</FunctionSettings>
);
}
import {extension, FunctionSettings, TextField, NumberField, Section} from '@shopify/ui-extensions/admin';

export default extension(
'admin.settings.validation.render',
async (root, api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};

const minField = root.createComponent(NumberField, {
value: initialSettings.minQuantity || 1,
label: 'Minimum order quantity',
name: 'minQuantity',
min: 1,
onChange(value) {
minField.updateProps({value});
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'min_quantity',
value: String(value),
valueType: 'number_integer',
});
},
});

const maxField = root.createComponent(NumberField, {
value: initialSettings.maxQuantity || 100,
label: 'Maximum order quantity',
name: 'maxQuantity',
min: 1,
onChange(value) {
maxField.updateProps({value});
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'max_quantity',
value: String(value),
valueType: 'number_integer',
});
},
});

const messageField = root.createComponent(TextField, {
value: initialSettings.errorMessage || '',
label: 'Error message shown to customers',
name: 'errorMessage',
onChange(value) {
messageField.updateProps({value});
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:validation',
key: 'error_message',
value,
valueType: 'single_line_text_field',
});
},
});

const section = root.createComponent(Section, {
heading: 'Quantity limits',
});

const settings = root.createComponent(FunctionSettings, {
onError(errors) {
const firstError = errors[0]?.message;
minField.updateProps({error: firstError});
},
});

section.appendChild(minField);
section.appendChild(maxField);
section.appendChild(messageField);
settings.appendChild(section);
root.appendChild(settings);
},
);

Anchor to Validate settings on saveValidate settings on save

Use the onSave callback to notify your backend when the admin saves changes. This example configures a discount function with a title and type ChoiceList, calling your validation endpoint during save and surfacing any errors through onError.

Validate settings on save

import {useState} from 'react';
import {reactExtension, useApi, FunctionSettings, TextField, ChoiceList, Section, BlockStack} from '@shopify/ui-extensions-react/admin';

export default reactExtension(
'admin.settings.validation.render',
async (api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};
return <App settings={initialSettings} />;
},
);

function App({settings}) {
const [title, setTitle] = useState(settings.title || '');
const [type, setType] = useState(settings.type || 'percentage');
const [error, setError] = useState();
const {applyMetafieldsChange} = useApi();

return (
<FunctionSettings
onSave={async () => {
await fetch('/api/functions/validate-config', {method: 'POST'});
}}
onError={(errors) => setError(errors[0]?.message)}
>
<Section heading="Discount configuration">
<BlockStack gap>
<TextField
label="Discount title"
name="title"
required
value={title}
error={error}
onChange={(value) => {
setTitle(value);
setError(undefined);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:discount',
key: 'title',
value,
valueType: 'single_line_text_field',
});
}}
/>
<ChoiceList
name="discountType"
value={type}
choices={[
{label: 'Percentage discount', id: 'percentage'},
{label: 'Fixed amount discount', id: 'fixed'},
]}
onChange={(value) => {
setType(value);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:discount',
key: 'type',
value,
valueType: 'single_line_text_field',
});
}}
/>
</BlockStack>
</Section>
</FunctionSettings>
);
}
import {extension, FunctionSettings, TextField, ChoiceList, Section, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
'admin.settings.validation.render',
async (root, api) => {
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};

const titleField = root.createComponent(TextField, {
value: initialSettings.title || '',
label: 'Discount title',
name: 'title',
required: true,
onChange(value) {
titleField.updateProps({value, error: undefined});
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:discount',
key: 'title',
value,
valueType: 'single_line_text_field',
});
},
});

const typeChoice = root.createComponent(ChoiceList, {
name: 'discountType',
value: initialSettings.type || 'percentage',
choices: [
{label: 'Percentage discount', id: 'percentage'},
{label: 'Fixed amount discount', id: 'fixed'},
],
onChange(value) {
api.applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:discount',
key: 'type',
value,
valueType: 'single_line_text_field',
});
},
});

const section = root.createComponent(Section, {
heading: 'Discount configuration',
});

const settings = root.createComponent(FunctionSettings, {
onSave: async () => {
await fetch('/api/functions/validate-config', {method: 'POST'});
},
onError(errors) {
titleField.updateProps({error: errors[0]?.message});
},
});

const content = root.createComponent(BlockStack, {gap: true});
content.appendChild(titleField);
content.appendChild(typeChoice);
section.appendChild(content);
settings.appendChild(section);
root.appendChild(settings);
},
);

Anchor to Best practicesBest practices

  • Group related settings logically: Organize the input fields inside FunctionSettings with Section and Heading components to create a clear, scannable settings interface.

Anchor to LimitationsLimitations

  • FunctionSettings doesn't include a built-in reset callback like Form. The save bar's discard behavior is managed by the Shopify admin.
  • FunctionSettings doesn't validate input values before save. You must implement your own validation logic and display errors on individual fields.
  • Only one FunctionSettings component should be used per extension view. Each FunctionSettings binds to the admin's save bar, and multiple instances would create conflicting save states.
Was this page helpful?