Skip to main content

FunctionSettings

FunctionSettings should be used when configuring the metafield configuration of a Shopify Function. It provides a structure for various input fields and controls, such as text fields, checkboxes, and selections. It also integrates with the native Contextual Save Bar to handle form submission and reset actions.

Anchor to functionsettingspropsFunctionSettingsProps

Anchor to id
id
string

A unique identifier for the form.

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

An optional callback function that will be run by the admin when the committing the changes to Shopify’s servers fails. The errors you receive in the errors argument will only be those that were caused by data your extension provided; network errors and user errors that are out of your control will not be reported here.

In the onError callback, you should update your extension’s UI to highlight the fields that caused the errors, and display the error messages to the user.

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

An optional callback function that will be run by the admin when the user commits their changes in the admin-rendered part of the function settings experience. If this function returns a promise, the admin will wait for the promise to resolve before committing any changes to Shopify’s servers. If the promise rejects, the admin will abort the changes and display an error, using the message property of the error you reject with.

Was this section helpful?

Simple function settings form implementation

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

export default reactExtension(
'admin.settings.validation.render',
async (api) => {
// Use Direct API access to fetch initial
// metafields from the server if we are
// rendering against a pre-existing `Validation`
const initialSettings = api.data.validation
? await fetchSettings(api.data.validation.id)
: {};

return <App settings={initialSettings} />;
});

function App({settings}) {
const [value, setValue] = useState(settings);
const [error, setError] = useState();

const {applyMetafieldsChange} = useApi();

return (
<FunctionSettings
onError={(errors) => {
setError(errors[0]?.message);
}}
>
<Section heading="Settings">
<TextField
label="Name"
name="name"
value={value}
error={error}
onChange={(value) => {
setValue(value);
setError(undefined);
applyMetafieldsChange({
type: 'updateMetafield',
namespace: '$app:my_namespace',
key: 'name',
value,
valueType: 'single_line_text_field',
});
}}
/>
</Section>
</FunctionSettings>
);
}

Preview

Anchor to relatedRelated

TextField
NumberField
ChoiceList