This guide explains all of the sidebar settings componenets that are available to be used in your plugin’s settings JSON configuration, giving your app users the ability to select and customize the HTML content they want to add into their email content.

​

Settings components

​

Color picker

Use the type: color setting config for a color picker.

{
  "type": "color",
  "name": "background_color",
  "label": "Background color",
  "required": true, // optional
  "help": "help text shown in tooltip to creator while editing" // optional
}

​

Font picker

Use the type: fontFamily setting config for a font family and font weight picker. Kit will automatically supply a list of email-friendly font families and their fallbacks.

{
  "type": "fontFamily",
  "name": "paragraph_font",
  "label": "Paragraph font",
  "required": true, // optional
  "help": "help text shown in tooltip to creator while editing" // optional
}

When requesting HTML, Kit will pass the user’s values for fontFamily fields as an object with a fontFamily and a fontWeight.

{
  "settings": {
    "yourFontFieldName": {
      "fontFamily": "'Courier New', Courier, monospace",
      "fontWeight": 400,
    }
  }
}

​

Date picker

Use the type: date setting config for a date picker.

All dates are returned in UTC, ISO8601 format such as: “2024-10-03T07:00:00.000Z”

{
  "type": "date",
  "name": "start_date",
  "label": "Start date",
  "required": false, // optional
  "help": "help text shown in tooltip to creator while editing" // optional
}

​

Search input

Use the type: search setting config for a search input.

{
  "type": "search",
  "name": "post",
  "label": "Post",
  "request_url": "https://example.com/path/to/your/search/endpoint",
  "placeholder": "Select a post", // optional
  "required": true, // optional
  "help": "help text shown in tooltip to creator while editing", // optional
  "dependencies": ["names", "of", "inputs", "to", "depend", "on"], // optional
  "multiselect": false // optional
}

When the plugin loads, Kit will make a request to your provided request_url with an empty string search param. This allows you to autopopulate the search dropdown with default results.

When the creator types into the search input, Kit will make a debounced request to your provided request_url to retrieve further filtered results.

{
  "search": "Query the user typed"
}

If a creator leaves their email in a draft state and edits again in the future, we’ll make a request to your provided request_url with the value of the option they had previously selected. This allows us to fill the dropdown with your user-friendly label.

The optional dependencies configuration allows you to wait to display a search input until the creator has entered values for all of the dependency inputs.

// if this is your search input configuration
{
  "type": "search",
  "name": "post",
  "label": "Post",
  "request_url": "https://example.com/path/to/your/search/endpoint",
  "dependencies": ["favorite_color"], // optional
}

// Kit will send a POST that includes the dependencies
{
  "favorite_color": "value user selected",
  "search": "Query the user typed"
}

Once all the dependencies have a value, your dependent search input will be displayed. And we will include the dependencies as parameters to your provided request_url.

You should return an array of objects, each with a label-value pair.

{
  "data": [
    {
      "label": "A post title",
      "value": "post-id-123"
    }
  ]
}

The label will be visible to users; it is used as the text for the result. The value is not visible to users, but will be sent when requesting HTML for your block.

If something goes wrong, we also accept an errors array.

{
  "data": [],
  "errors": ["Plan not found"]
}

If you configure multiselect: true, then the creator will be able to select multiple options. This will be sent as an array of strings to your request_url.

// if this is your search input configuration
{
  "type": "search",
  "name": "foods",
  "label": "Favorite foods",
  "request_url": "https://example.com/path/to/your/search/endpoint",
  "multiselect": true // optional
}

// Kit will send a POST with the `foods` value as an array
{
  "foods": ["values", "user", "selected]
}

​

Select input

Use the type: select setting config for a select input, commonly called a “dropdown menu” with a predefined list of options. The chosen value is not visible to users, but will be sent when requesting HTML for your block.

  "type": "select",
  "name": "favorite_food",
  "label": "Favorite food",
  "options": [
    {
      "label": "French fries",
      "value": "food-id-1"
    },
    {
      "label": "Hash browns",
      "value": "food-id-2"
    },
    {
      "label": "Potato chips",
      "value": "food-id-3"
    }
  ],
  "placeholder": "Select a food...", // optional
  "required": true, // optional
  "help": "help text shown in tooltip to creator while editing" // optional
}

​

Text input

Use the type: text setting config for a single-line text input useful for entering short snippets of text.

{
  "type": "text",
  "name": "title",
  "label": "Title",
  "placeholder": "Enter a title...", // optional
  "required": true, // optional
  "help": "help text shown in tooltip to creator while editing" // optional
}

​

Global configuration options

​

Required settings

You can optionally add required: true to a setting. We won’t request HTML from your server until all required settings are complete.

​

Help text

You can optionally add help text for creators when using your plugin. You can add help: "some help text" to any setting and we’ll render a tooltip on your input label with your help text.

​

Refreshing data

After a user has configured all required settings, we will perform a request to your server for the block’s HTML. If the user wants to refresh the data, they can either:

1. Click the refresh button that appears when hovering over the element (pictured below), or
2. Change one of your plugin’s settings in the sidebar, which will automatically kick off another request for new HTML.