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