External

Select data from a list, typically populated via a third-party API. Extends Base.

Interactive Demo

Example

No data selected

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            // ... fetch data from a third party API, or other async source
 
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
        },
      },
      render: ({ data }) => {
        return <p>{data?.title || "No data selected"}</p>;
      },
    },
  },
};

Params

Param	Example	Type	Status
`type`	`type: "external"`	"external"	Required
`fetchList()`	`fetchList: async () => []`	Function	Required
`filterFields`	`{ "rating": { type: "number" } }`	Object	-
`getItemSummary()`	`getItemSummary: async ({ title }) => title`	Function	-
`initialFilters`	`{ "rating": 1 }`	Object	-
`initialQuery`	`initialQuery: "Hello, world"`	String	-
`mapProp()`	`mapProp: async ({ title }) => title`	Function	-
`mapRow()`	`mapRow: async ({ title }) => title`	Function	-
`placeholder`	`placeholder: "Select content"`	String	-
`showSearch`	`showSearch: true`	Boolean	-

Required params

`type`

The type of the field. Must be "external" for Array fields.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
        },
      },
      // ...
    },
  },
};

`fetchList(queryParams)`

Return a promise with a list of objects to be rendered in a tabular format via the external input modal.

The table will only render strings and numbers.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            // ... fetch data from a third party API, or other async source
 
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
        },
      },
      // ...
    },
  },
};

`queryParams`

The parameters passed to the fetchList method based on your field configuration.

Param	Example	Type
`query`	`"My Query"`	String
`filters`	`"{ "rating": 1 }"`	Object

`query`

The search query when using showSearch.

`filters`

An object describing the filters configured by filterFields.

Optional params

`filterFields`

An object describing filters for your query using the Fields API

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async ({ filters }) => {
            return [
              { title: "Apple", description: "Lorem ipsum 1", rating: 5 },
              { title: "Orange", description: "Lorem ipsum 2", rating: 3 },
            ].filter((item) => item.rating >= (filters.rating || 0));
          },
          filterFields: {
            rating: {
              type: "number",
            },
          },
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`getItemSummary(item)`

Get the label to show once the item is selected.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
          getItemSummary: (item) => item.title,
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

Hello, world

`initialFilters`

The initial filter values when using filterFields.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async ({ filters }) => {
            return [
              { title: "Apple", description: "Lorem ipsum 1", rating: 5 },
              { title: "Orange", description: "Lorem ipsum 2", rating: 3 },
            ].filter((item) => item.rating >= (filters.rating || 0));
          },
          filterFields: {
            rating: {
              type: "number",
            },
          },
          initialFilters: {
            rating: 1,
          },
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`initialQuery`

Set an initial query when using showing a search input with showSearch.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async ({ query }) => {
            return [
              { title: "Apple", description: "Lorem ipsum 1" },
              { title: "Orange", description: "Lorem ipsum 2" },
            ].filter((item) => {
              // ...
            });
          },
          showSearch: true,
          initialQuery: "Apple",
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`mapProp(item)`

Modify the shape of the item selected by the user in the table before writing to the page data.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
          mapProp: (item) => item.description,
        },
      },
      render: ({ data }) => {
        return <p>{data || "No data selected"}</p>;
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`mapRow(item)`

Modify the shape of the item before rendering it in the table. This will not affect the selected data.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            return [
              { title: "Hello, world", description: "Lorem ipsum 1" },
              { title: "Goodbye, world", description: "Lorem ipsum 2" },
            ];
          },
          mapRow: (item) => ({ ...item, title: item.title.toUpperCase() }),
        },
      },
      render: ({ data }) => {
        return <p>{data || "No data selected"}</p>;
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`placeholder`

Set the placeholder text when no item is selected.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            return [
              { title: "Apple", description: "Lorem ipsum 1" },
              { title: "Orange", description: "Lorem ipsum 2" },
            ];
          },
          placeholder: "Pick your favorite fruit",
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

`showSearch`

Show a search input, the value of which will be passed to fetchList as the query param.

const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async ({ query }) => {
            return [
              { title: "Apple", description: "Lorem ipsum 1" },
              { title: "Orange", description: "Lorem ipsum 2" },
            ].filter((item) => {
              // ...
            });
          },
          showSearch: true,
        },
      },
      // ...
    },
  },
};

Interactive Demo

Example

No data selected

Custom Number