---
title: Marketing activities components reference
description: Learn about the different components that you can use to build a marketing activity form.
api_name: marketing-activities
source_url:
  html: https://shopify.dev/docs/api/marketing-activities/components
  md: https://shopify.dev/docs/api/marketing-activities/components.md
---

ExpandOn this page

* [How it works](https://shopify.dev/docs/api/marketing-activities/components#how-it-works)
* [Extensions configured with Shopify CLI](https://shopify.dev/docs/api/marketing-activities/components#extensions-configured-with-shopify-cli)
* [Single line of text](https://shopify.dev/docs/api/marketing-activities/components#single-line-of-text)
* [Multiple lines of text](https://shopify.dev/docs/api/marketing-activities/components#multiple-lines-of-text)
* [Number](https://shopify.dev/docs/api/marketing-activities/components#number)
* [Select from choice list](https://shopify.dev/docs/api/marketing-activities/components#select-from-choice-list)
* [Budget](https://shopify.dev/docs/api/marketing-activities/components#budget)
* [Schedule](https://shopify.dev/docs/api/marketing-activities/components#schedule)
* [Product selection](https://shopify.dev/docs/api/marketing-activities/components#product-selection)
* [Discount selection](https://shopify.dev/docs/api/marketing-activities/components#discount-selection)
* [Image selection](https://shopify.dev/docs/api/marketing-activities/components#image-selection)
* [Typeahead](https://shopify.dev/docs/api/marketing-activities/components#typeahead)
* [Title and body display text](https://shopify.dev/docs/api/marketing-activities/components#title-and-body-display-text)
* [Divider](https://shopify.dev/docs/api/marketing-activities/components#divider)

# Marketing activities components reference

Deprecated

The creation of new marketing activity app extensions is deprecated. Only existing extensions can still be managed. If you have an existing marketing activity app extension and would like to continue to manage it, please migrate it to CLI following the [migration guide](https://shopify.dev/docs/apps/build/marketing-analytics/marketing-activities/migrate-extensions).

The form that's associated with a marketing activity app extension is generated based on a set of components that you choose when you create it. Components are configurable pieces of UI that you can use to build out the specific functionality that your app requires. Although a form is generated based on the components that you choose, you can't customize its styling, layout, or workflows directly.

***

## How it works

When an app user interacts with your marketing activity, Shopify calls your marketing activity [preload endpoint](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form) to render the field values that your app provides. To do this Shopify uses the components in JSON format, as defined in this document. The JSON format is also used for your app's other endpoints such as [create](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity) and [update](https://shopify.dev/docs/api/marketing-activities/endpoints#update-a-marketing-activity).

### Preload endpoint JSON output schema

Responses from your app's [preload endpoint](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form) include the `form_data` at the top level with `field_name` and property key value pairs.

```json
{
  "form_data": {
    "<field_name>": {
      "<property_key>": "<property_value>"
    }
  }
}
```

For the [dynamic standalone endpoint](https://shopify.dev/docs/api/marketing-activities/endpoints#dynamic-standalone-fields), responses from your app include `component_data` at the top level. Refer to the [typeahead component](https://shopify.dev/docs/api/marketing-activities/components#typeahead) for more information.

```json
{
  "component_data": {
    "options": [{"label": "<option_label>", "value": "<option_value>"}]
  }
}
```

### Create or update JSON input schema

When a user creates or updates a marketing activity, Shopify calls your app by sending the properties object with the included field names and corresponding values.

```json
{
  ...
  "properties": {
    "<field_name>": "<value>"
  }
}
```

***

## Extensions configured with Shopify CLI

[Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps) builds and serves app extensions using information defined in a TOML file. Components are specified in the `fields` section of your marketing activity extension's TOML file. The following is an example TOML file:

## shopify.extension.toml

```toml
[[extensions]]
type = "marketing_activity"
name = "My Marketing Activity"
handle = "first-marketing-activity"
title = "Amazing Marketing Activity"
description = "Create an advertisement"
api_path = "/marketing_activities"
tactic = "ad"
marketing_channel = "social"
referring_domain = "example.com"


[[extensions.preview_data.types]]
label = "Desktop"
value = "desktop"


[[extensions.preview_data.types]]
label = "Mobile"
value = "mobile"


[[extensions.fields]]
name = "budget_id"
ui_type = "budget-schedule"
required = true
label = "Enter a budget for the ad"
use_daily_budget = true
use_lifetime_budget = false
use_scheduling = false
use_end_date = false


[[extensions.fields]]
name = "image_id"
ui_type = "image-picker"
required = true
label = "Add images"
help_text = "Select your images"
min_resources = 0
max_resources = 3
allow_free_images = true
alt_text_required = true
```

For every component in `fields`, regardless of the type, the following subfields are mandatory:

| Subfield | Description |
| - | - |
| `name` required | The API identifier. Use `snake_case`: lowercase letters, numbers, and underscores only. |
| `ui_type` required | The type of the field component. |

Each type of component requires different additional subfields. For a complete reference, and to determine the `ui_type` of the component you wish to configure, read on.

***

## Single line of text

Use this component to let users provide text input when the expected input is short.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the component. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |
| `max_length` | Number | The maximum number of characters allowed. |
| `min_length` | Number | The minimum number of characters allowed. |
| `placeholder` | String | The hint text to display. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | String | The value of the input. |

#### Preload endpoint JSON output example

The example JSON below defines the help text and value of the `ad_title` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "ad_title": {
      "help_text": "Think of something creative!",
      "value": "Welcome to John's apparel store."
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `ad_title` field.

```json
{
  ...
  "properties": {
    "ad_title": "Welcome to John's crazy apparel store."
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type` required | Must be one of `text-single-line`, `text-email`, `text-tel`, `text-url` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `placeholder` | String |
| `min_length` required | Number |
| `max_length` required | Number |

***

## Multiple lines of text

Use this component when the expected input could be more than one line. The component will automatically grow to accommodate additional text.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the component. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |
| `max_length` | Number | The maximum number of characters allowed. |
| `min_length` | Number | The minimum number of characters allowed. |
| `placeholder` | String | The hint text to display. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | String | The value of the input. |

#### Preload endpoint JSON output example

The example JSON below defines the help text and value of the `ad_body` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "ad_body": {
      "help_text": "Include a lot of information about your product.",
      "value": "This shirt is the best.\n\nIt's made with high quality materials."
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `ad_body` field.

```json
{
  ...
  "properties": {
    "ad_body": "These shorts are the best.\n\nThey're made with quality materials."
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type` required | `text-multi-line` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `placeholder` required | String |
| `min_length` required | Number |
| `max_length` required | Number |

***

## Number

Use this component to let users provide number input.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the component. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |
| `max` | Number | The maximum number allowed. |
| `min` | Number | The minimum number allowed. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `step` | Number | The interval between valid values. Default: `1`. |
| `value` | Number | The value of the input. |

#### Preload endpoint JSON output example

The example JSON below defines the value of the `quantity` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "quantity": {
      "value": 1
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `quantity` field.

```json
{
  ...
  "properties": {
    "quantity": 10
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type` required | Must be one of `number-float`, `number-integer` |
| `label` required | String |
| `required` required | String |
| `help_text` | String |
| `min` required | Number |
| `max` required | Number |
| `step` required | Number |

***

## Select from choice list

Use this component to let users select choices from a list.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `choices` | Object\[] | The list of options to choose from. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `selected` | String\[] | A collection of selected choices. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below defines the choices and selected values of the `sizes` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "sizes": {
      "choices": [
        {"label": "Small", "value": "sm"},
        {"label": "Medium", "value": "md", "disabled": true},
        {"label": "Large", "value": "lg"}
      ],
      "selected": ["sm", "lg"]
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `sizes` field.

```json
{
  ...
  "properties": {
    "sizes": ["sm"]
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | Must be one of `select-single`, `select-multiple` |
| `label` required | String |
| `required` required | String |
| `help_text` | String |
| `choices` required | Array: each item must contain `label: String` & `value: String` |

***

## Budget

Use this component to let users set budget amounts.

Note

The currency property is required on the [preload API call](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `amount` | Numeric String | The budget amount |
| `currency*` | [CurrencyCode](https://shopify.dev/docs/api/admin-graphql/latest/enums/currencycode) | The currency to be used for the budget (set by the preload endpoint). |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the amount. |
| `max_amount` | Numeric String | The maximum budget amount |
| `min_amount` | Numeric String | The minimum budget amount |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `type` | String | The type of budget (`daily` or `lifetime`). |
| `use_daily_budget` | Boolean | Whether the user can enter a daily budget. Default: `false`. |
| `use_lifetime_budget` | Boolean | Whether the user can enter a lifetime budget. Both this and `use_daily_budget` can be checked, and at least one of them must be checked. Default: `false`. |
| `use_total_budget`(deprecated) | Boolean | Whether the user can enter a total budget. Both this and `use_daily_budget` can be checked, and at least one of them must be checked. Default: `false`. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below defines the amount, currency, help text, range start, range end and scheduling of `budget` the field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "budget": {
      "amount": 5,
      "currency": "CAD",
      "help_text": "Your shop will perform best with a $20 daily budget."
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `budget` field.

```json
{
  ...
  "properties": {
    "budget": {
      "amount": 20,
      "currency": "CAD",
      "type": "daily"
    }
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `budget-schedule` |
| `label` required | String |
| `required` required | String |
| `help_text` | String |
| `use_scheduling` | Boolean |
| `use_end_date` | Boolean |
| `use_daily_budget` required | Boolean |
| `use_lifetime_budget` required | Boolean |

***

## Schedule

Use this component to let users provide a start and end date.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the component. |
| `end_time` | [Date](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Date) | The user's selected end date. |
| `start_time` | [Date](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Date) | The user's selected start date. |
| `use_end_date` | Boolean | Whether the user can select an end date (in addition to a start date). Default: `false`. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below hides the end date of the `start_at` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "start_at": {
      "range_start": "2019-01-01T00:00:00.000Z",
      "use_end_date": false
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `start_at` field.

```json
{
  ...
  "properties": {
    "start_at": {
      "start_time": "2019-01-01T00:00:00.000Z",
    }
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `schedule` |
| `label` required | String |
| `required` required | String |
| `help_text` | String |
| `use_end_date` required | Boolean |

***

## Product selection

Use this component to let the user select one or more products and product images.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the resource picker. |
| `max_resources` | Number | The maximum number of selected resources allowed. |
| `min_resources` | Number | The minimum number of selected resources allowed. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | [Product](#product-type)\[] | An array of selected resources. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Product type

| Name | Type | Description |
| - | - | - |
| `id` | String | The product's ID. |
| `images` | {src: String; id?: String}\[] | The product's images. |
| `image_url`(deprecated) | String | The product's image. **Note:** Use `images` property to allow users to select product images. |

#### Preload endpoint JSON output example

The example JSON below defines the help text, maximum selected resources allowed and value of the `products` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "products": {
      "help_text": "Choose products that are featured on your home page.",
      "max_resources": 3,
      "value": [
        {
          "id": "gid://shopify/Product/5",
          "images": [
            {
              "src": "https://shopify.com/images/1"
            }
          ]
        }
      ]
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `products` field.

```json
{
  ...
  "properties": {
    "products": [
      {
        "id": "gid://shopify/Product/5",
        "image_url": "https://cdn.shopify.com/s/files/1",
        "title": "Blue swim shorts",
      },
      {
        "id": "gid://shopify/Product/6",
        "image_url": null,
        "title": "Straw hat",
      }
    ]
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `product-picker` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `allow_product_image_selection` required | Boolean |
| `allow_uploaded_image_as_product_image` required | Boolean |
| `allow_free_image_as_product_image` required | Boolean |
| `min_resources` | Number |
| `max_resources` | Number |
| `min_image_select_per_product` | Number |
| `max_image_select_per_product` | Number |

***

## Discount selection

Use this component to let the user select one or more discounts.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the resource picker. |
| `max_resources` | Number | The maximum number of selected resources allowed. |
| `min_resources` | Number | The minimum number of selected resources allowed. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | Object\[] | An array of selected resources. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below hides the end date of the `start_at` field that's defined in your Partner Dashboard.

```json
{
  "form_data": {
    "discount": {
      "help_text": "Choose a discount for this activity.",
      "max_resources": 1,
      "value": [
        {
          "id": "gid://shopify/PriceRule/1"
        }
      ]
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `discount` field.

```json
{
  ...
  "properties": {
    "discount": [
      {
        "id": "gid://shopify/PriceRule/1",
        "title": "BLACKFRIDAY10",
        "summary": "10% off entire order",
        "features": [],
        "status": "ACTIVE"
      }
    ]
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `discount-picker` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `min_resources` | Number |
| `max_resources` | Number |

***

## Image selection

Use this component to let the user either upload images to their shop or select images from their shop.

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `help_text` | String | The help text that's displayed under the resource picker. |
| `max_resources` | Number | The maximum number of selected resources allowed. |
| `min_resources` | Number | The minimum number of selected resources allowed. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | {src: String; id: String, altText: String, originalSrc (deprecated): String}\[] | An array of selected resources. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below defines the help text, maximum selected resources allowed and value of the `featured_images` field defined using the Partner Dashboard.

```json
{
  "form_data": {
    "featured_images": {
      "help_text": "Choose an image for this activity.",
      "max_resources": 3,
      "value": [
        {
          "id": "gid://shopify/ShopImage/1",
          "alt_text": "Blue sweater",
          "src": "https://cdn.myshopify.io/s/files/1/0000/0001/files/googlee.jpg"
        },
        {
          "id": "4289",
          "alt_text": "Black friday!",
          "src": "https://burst.shopifycdn.com/photos/i-heart-black-friday.jpg"
        }
      ]
    }
  }
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `featured_images` field.

```json
{
  ...
  "properties": {
    "featured_images": [
      {
        "id":"gid://shopify/ShopImage/1",
        "src":"https://cdn.shopify.com/s/files/1/1/1/files/blue_shorts.png?v=1517010629",
        "alt_text":"Blue shorts"
      },
      {
        "id":"gid://shopify/ShopImage/2",
        "src":"https://cdn.shopify.com/s/files/1/1/1/files/red_shorts.png?v=1517010629",
        "alt_text":"Red shorts"
      }
    ]
  }
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `image-picker` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `min_resources` | Number |
| `max_resources` | Number |
| `allow_free_images required` | Number |
| `alt_text_required required` | Number |

***

## Typeahead

Use this component to allow users to quickly search for items from a list.

Note

The typeahead component is populated by the [dynamic standalone endpoint](https://shopify.dev/docs/api/marketing-activities/endpoints#dynamic-standalone-fields) when the user interacts with the component.

#### Dynamic standalone endpoint JSON schema

```json
{
"field_data": {
  "options": [{"label": "<option_label>", "value": "<option_value>"}]
}
}
```

To learn more about the dynamic standalone endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#dynamic-standalone-fields).

### Endpoint JSON properties

The JSON representation of this component, used for marketing activity endpoints, is the following:

| Name | Type | Description |
| - | - | - |
| `field_name` | String | The name of the field, specified when you create the form. |
| `disabled` | Boolean | Whether the input is disabled. Default: `false`. |
| `placeholder` | String | The hint text to display. |
| `required` | Boolean | Whether the component is marked as required. Default: `true`. |
| `value` | Object\[] | A collection of selected choices. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

#### Preload endpoint JSON output example

The example JSON below defines the value of the `colours` field defined using the Partner Dashboard.

```json
{
"form_data": {
  "colours": {
    "value": [
      {"label": "Red", "value": "red"},
      {"label": "Blue", "value": "blue"},
      {"label": "Yellow", "value": "yellow"}
    ]
  }
}
}
```

To learn more about the preload endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#preload-a-marketing-activity-form).

#### Create or update JSON input example

The example below includes Shopify's response to your app with the user-provided value for the `colours` field.

```json
{
...
"properties": {
  "colours": [
      {"label": "Red", "value": "red"},
      {"label": "Blue", "value": "blue"}
    ]
  }
}
}
```

To learn more about the create or update endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#create-a-marketing-activity).

#### Dynamic standalone endpoint JSON output example

The example JSON below defines the options of the `colours` field defined using the Partner Dashboard.

```json
{
"field_data": {
  "options": [
    {"label": "Red", "value": "red"},
    {"label": "Blue", "value": "blue"},
    {"label": "Yellow", "value": "yellow"}
  ]
}
}
```

To learn more about the dynamic standalone endpoint, refer to the [marketing activity endpoints](https://shopify.dev/docs/api/marketing-activities/endpoints#dynamic-standalone-fields).

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `type-ahead` |
| `label` required | String |
| `required` required | Boolean |
| `help_text` | String |
| `placeholder` required | String |

***

## Title and body display text

Use this component to provide extra information to the user about the task that they're completing.

Note

The title and body display text component is configured using the Partner Dashboard. It can't be set on preload and is not included in form submission.

### Component properties

| Name | Type | Description |
| - | - | - |
| `title` | String | The section title. |
| `body` | String | The section body.Supports relative or secure HTTPS absolute links using markdown. For example:`Click here to set up your account.` or `Read more about account setup.` |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `paragraph` |
| `heading` | String |
| `body` | String |

***

## Divider

Use this component to group related components into sections.

Note

The divider component is configured in the Partner Dashboard by hovering between components and providing a section title. It can't be set on preload and is not included in form submission.

### Component properties

| Name | Type | Description |
| - | - | - |
| `title` | String | The section title. |
| `hidden` | Boolean | Whether the component is hidden. Default: `false`. |

### CLI configuration

To configure this component in your extension TOML, add a `fields` item entry with the following:

| Name | Type |
| - | - |
| `ui_type`required | `divider` |
| `title`required | String |

***

* [How it works](https://shopify.dev/docs/api/marketing-activities/components#how-it-works)
* [Extensions configured with Shopify CLI](https://shopify.dev/docs/api/marketing-activities/components#extensions-configured-with-shopify-cli)
* [Single line of text](https://shopify.dev/docs/api/marketing-activities/components#single-line-of-text)
* [Multiple lines of text](https://shopify.dev/docs/api/marketing-activities/components#multiple-lines-of-text)
* [Number](https://shopify.dev/docs/api/marketing-activities/components#number)
* [Select from choice list](https://shopify.dev/docs/api/marketing-activities/components#select-from-choice-list)
* [Budget](https://shopify.dev/docs/api/marketing-activities/components#budget)
* [Schedule](https://shopify.dev/docs/api/marketing-activities/components#schedule)
* [Product selection](https://shopify.dev/docs/api/marketing-activities/components#product-selection)
* [Discount selection](https://shopify.dev/docs/api/marketing-activities/components#discount-selection)
* [Image selection](https://shopify.dev/docs/api/marketing-activities/components#image-selection)
* [Typeahead](https://shopify.dev/docs/api/marketing-activities/components#typeahead)
* [Title and body display text](https://shopify.dev/docs/api/marketing-activities/components#title-and-body-display-text)
* [Divider](https://shopify.dev/docs/api/marketing-activities/components#divider)