---
title: Function settings
description: >-
  The function settings component configures metafield settings for Shopify
  Functions. Use function settings to create configuration interfaces that allow
  merchants to customize function behavior through structured input fields and
  controls.
api_version: 2026-01
api_name: admin-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/function-settings
  md: >-
    https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/function-settings.md
---

# Function settings

**Requires the \[Discount Function Settings API]\(/docs/api/admin-extensions/2026-01/target-apis/contextual-apis/discount-function-settings-api), \[Validation Settings API]\(/docs/api/admin-extensions/2026-01/target-apis/contextual-apis/validation-settings-api), or \[Order Routing Rule API]\(/docs/api/admin-extensions/2026-01/target-apis/contextual-apis/order-routing-rule-api).:**

The function settings component configures metafield settings for [Shopify Functions](https://shopify.dev/docs/api/functions). Use function settings 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 and reset actions automatically. For general form submission, use [form](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/form).

### Support Targets (3)

### Supported targets

* [admin.​discount-details.​function-settings.​render](https://shopify.dev/docs/api/admin-extensions/2026-01/targets/function-settings#discount-details-function-settings-)
* [admin.​settings.​order-routing-rule.​render](https://shopify.dev/docs/api/admin-extensions/2026-01/targets/function-settings#order-routing-rule-function-settings-)
* [admin.​settings.​validation.​render](https://shopify.dev/docs/api/admin-extensions/2026-01/targets/function-settings#validation-function-settings-)

#### Use cases

* **Function configuration:** Build settings interfaces for Shopify Functions that store configuration in metafields.
* **Validation rules:** Create configuration UIs for cart and checkout validation Functions.
* **Discount settings:** Configure discount Function settings with proper save bar integration.
* **Shipping customization:** Build settings panels for shipping or delivery customization Functions.

### Events

The form component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **reset**

  **CallbackEventListener\<typeof tagName> | null**

  **required**

  A callback that is run when the form is reset.

* **submit**

  **CallbackExtendableEventListener\<typeof tagName> | null**

  **required**

  A callback that is run when the form is submitted.

### CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a \`CallbackEvent\` with a strongly-typed \`currentTarget\`. Use this for component event handlers like \`click\`, \`focus\`, \`blur\`, and other DOM events.

```ts
(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null
```

### CallbackEvent

An event object with a strongly-typed \`currentTarget\` property that references the specific HTML element that triggered the event. This type extends the standard DOM \`Event\` interface and ensures type safety when accessing the element that fired the event.

```ts
Event & {
  currentTarget: HTMLElementTagNameMap[T];
}
```

### CallbackExtendableEventListener

A function that handles extendable events from UI components. This type represents an event listener callback that can use \`waitUntil\` to extend the event lifetime.

```ts
(EventListener & {
      (event: CallbackExtendableEvent<TTagName>): void;
    }) | null
```

### CallbackExtendableEvent

* AT\_TARGET

  ```ts
  2
  ```

* bubbles

  The \*\*\`bubbles\`\*\* read-only property of the Event interface indicates whether the event bubbles up through the DOM tree or not. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/bubbles)

  ```ts
  boolean
  ```

* BUBBLING\_PHASE

  ```ts
  3
  ```

* cancelable

  The \*\*\`cancelable\`\*\* read-only property of the Event interface indicates whether the event can be canceled, and therefore prevented as if the event never happened. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/cancelable)

  ```ts
  boolean
  ```

* cancelBubble

  The \*\*\`cancelBubble\`\*\* property of the Event interface is deprecated.

  ```ts
  boolean
  ```

* CAPTURING\_PHASE

  ```ts
  1
  ```

* composed

  The read-only \*\*\`composed\`\*\* property of the or not the event will propagate across the shadow DOM boundary into the standard DOM. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/composed)

  ```ts
  boolean
  ```

* composedPath

  The \*\*\`composedPath()\`\*\* method of the Event interface returns the event's path which is an array of the objects on which listeners will be invoked. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/composedPath)

  ```ts
  () => EventTarget[]
  ```

* currentTarget

  The \*\*\`currentTarget\`\*\* read-only property of the Event interface identifies the element to which the event handler has been attached. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/currentTarget)

  ```ts
  EventTarget | null
  ```

* defaultPrevented

  The \*\*\`defaultPrevented\`\*\* read-only property of the Event interface returns a boolean value indicating whether or not the call to Event.preventDefault() canceled the event. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/defaultPrevented)

  ```ts
  boolean
  ```

* eventPhase

  The \*\*\`eventPhase\`\*\* read-only property of the being evaluated. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/eventPhase)

  ```ts
  number
  ```

* initEvent

  The \*\*\`Event.initEvent()\`\*\* method is used to initialize the value of an event created using Document.createEvent().

  ```ts
  (type: string, bubbles?: boolean, cancelable?: boolean) => void
  ```

* isTrusted

  The \*\*\`isTrusted\`\*\* read-only property of the when the event was generated by the user agent (including via user actions and programmatic methods such as HTMLElement.focus()), and \`false\` when the event was dispatched via The only exception is the \`click\` event, which initializes the \`isTrusted\` property to \`false\` in user agents. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/isTrusted)

  ```ts
  boolean
  ```

* NONE

  ```ts
  0
  ```

* preventDefault

  The \*\*\`preventDefault()\`\*\* method of the Event interface tells the user agent that if the event does not get explicitly handled, its default action should not be taken as it normally would be. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/preventDefault)

  ```ts
  () => void
  ```

* returnValue

  The Event property \*\*\`returnValue\`\*\* indicates whether the default action for this event has been prevented or not.

  ```ts
  boolean
  ```

* srcElement

  The deprecated \*\*\`Event.srcElement\`\*\* is an alias for the Event.target property.

  ```ts
  EventTarget | null
  ```

* stopImmediatePropagation

  The \*\*\`stopImmediatePropagation()\`\*\* method of the If several listeners are attached to the same element for the same event type, they are called in the order in which they were added. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/stopImmediatePropagation)

  ```ts
  () => void
  ```

* stopPropagation

  The \*\*\`stopPropagation()\`\*\* method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/stopPropagation)

  ```ts
  () => void
  ```

* target

  The read-only \*\*\`target\`\*\* property of the dispatched. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/target)

  ```ts
  EventTarget | null
  ```

* timeStamp

  The \*\*\`timeStamp\`\*\* read-only property of the Event interface returns the time (in milliseconds) at which the event was created. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/timeStamp)

  ```ts
  DOMHighResTimeStamp
  ```

* type

  The \*\*\`type\`\*\* read-only property of the Event interface returns a string containing the event's type. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Event/type)

  ```ts
  string
  ```

* waitUntil

  A method that accepts a promise signaling the duration and eventual success or failure of event-related actions. Can be called multiple times to add promises to the event, but must be called synchronously during event dispatch. Cannot be called after a \`setTimeout\` or within a microtask.

  ```ts
  (promise: Promise<void>) => void
  ```

***

## Examples

### Add a settings field for a function

Configure a [Shopify Function](https://shopify.dev/docs/api/functions/) with a settings form that integrates with the native save bar. This example shows a [number field](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/number-field) for a discount percentage input inside a function settings component.

## html

```html
<s-function-settings>
  <s-number-field
    step="1"
    suffix="%"
    label="Percentage"
    name="percentage"
    value="10"
  ></s-number-field>
</s-function-settings>
```

### Set up tiered discount rules

Organize settings into repeating groups for tiered or multi-level configurations. This example uses [sections](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/layout-and-structure/section) to define two volume discount tiers, each with a quantity threshold and percentage.

## html

```html
<s-function-settings>
  <s-stack direction="block" gap="base">
    <s-section heading="Tier 1">
      <s-stack direction="inline" gap="base">
        <s-number-field label="Minimum quantity" name="tier1Qty" value="5" min="1" step="1"></s-number-field>
        <s-number-field label="Discount" name="tier1Discount" value="10" min="0" max="100" step="1" suffix="%"></s-number-field>
      </s-stack>
    </s-section>
    <s-section heading="Tier 2">
      <s-stack direction="inline" gap="base">
        <s-number-field label="Minimum quantity" name="tier2Qty" value="10" min="1" step="1"></s-number-field>
        <s-number-field label="Discount" name="tier2Discount" value="20" min="0" max="100" step="1" suffix="%"></s-number-field>
      </s-stack>
    </s-section>
  </s-stack>
</s-function-settings>
```

### Show validation errors on settings

Display validation errors when settings values are out of range or missing. This example shows required [number fields](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/number-field) with inline error messages.

## html

```html
<s-function-settings>
  <s-stack direction="block" gap="base">
    <s-number-field
      step="1"
      suffix="%"
      label="Discount percentage"
      name="percentage"
      min="0"
      max="100"
      required
      error="Enter a percentage between 0 and 100"
    ></s-number-field>
    <s-number-field
      step="0.01"
      prefix="$"
      label="Maximum discount amount"
      name="maxDiscount"
      min="0"
      required
      error="Enter a positive dollar amount"
    ></s-number-field>
  </s-stack>
</s-function-settings>
```

### Add a select dropdown to settings

Let merchants choose from predefined options to control function behavior. This example uses a [select](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/select) dropdown to pick a discount target and a [text field](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/text-field) for a filter value.

## html

```html
<s-function-settings>
  <s-stack direction="block" gap="base">
    <s-select label="Apply discount to" name="target">
      <s-option value="all">All products</s-option>
      <s-option value="collection">Specific collection</s-option>
      <s-option value="tagged">Products with tag</s-option>
    </s-select>
    <s-text-field label="Collection or tag" name="identifier"></s-text-field>
  </s-stack>
</s-function-settings>
```

### Toggle a feature with a switch

Let merchants enable or disable a feature with a [switch](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/switch) and configure its threshold. This example pairs a toggle for free shipping with a minimum order amount [number field](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/number-field).

## html

```html
<s-function-settings>
  <s-stack direction="block" gap="base">
    <s-switch label="Enable free shipping threshold" name="freeShippingEnabled" checked></s-switch>
    <s-number-field
      step="0.01"
      prefix="$"
      label="Minimum order amount"
      name="freeShippingThreshold"
      value="75.00"
      min="0"
    ></s-number-field>
  </s-stack>
</s-function-settings>
```

***

## Best practices

* **Label settings clearly:** Instead of technical names like **Max threshold**, use merchant-friendly labels like **Maximum discount amount** or **Order value limit**.
* **Validate with specific feedback:** Check that percentages are between 0-100, that monetary values are positive, and that required fields are filled. Provide clear error messages when validation fails.
* **Explain impact with field details:** Use the `details` property on individual field components (for example, [text field](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/text-field) or [number field](https://shopify.dev/docs/api/admin-extensions/2026-01/web-components/forms/number-field)) to explain what each setting does and how it affects the user's workflow.
* **Set appropriate defaults:** Pre-select the most common configuration to reduce setup friction for merchants.
* **Group related settings:** Use sections to organize settings by function so merchants can find what they need quickly.

***