Choose a version:

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.

FunctionSettingsProps

id
A unique identifier for the form.
```
string
```
onError
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.
```
(errors: FunctionSettingsError[]) => void
```
onSave
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.
```
() => void | Promise<void>
```

export interface FunctionSettingsProps {
  /**
   * A unique identifier for the form.
   */
  id?: string;

  /**
   * 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.
   */
  onSave?(): void | Promise<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.
   */
  onError?(errors: FunctionSettingsError[]): void;
}

FunctionSettingsError

code
A unique identifier describing the “class” of error. These will match the GraphQL error codes as closely as possible. For example the enums returned by the `metafieldsSet` mutation
```
string
```
message
A translated message describing the error.
```
string
```

export interface FunctionSettingsError {
  /**
   * A unique identifier describing the “class” of error. These will match
   * the GraphQL error codes as closely as possible. For example the enums
   * returned by the `metafieldsSet` mutation
   *
   * @see /docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode
   */
  code: string;

  /**
   * A translated message describing the error.
   */
  message: string;
}

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

}}

<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>

);

}

examples

Simple function settings form implementation

React

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

JS

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

export default extension(
  'admin.settings.validation.render',
  async (root, 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)
      : {};

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

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

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

    section.append(textField);
    settings.append(section);
  },
);

Preview

Anchor to relatedRelated

TextField

NumberField

ChoiceList