External
Select data from a list, typically populated via a third-party API. Extends Base.
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",
},
},
},
},
// ...
},
},
};
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,
},
},
// ...
},
},
};
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,
},
},
},
// ...
},
},
};
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",
},
},
// ...
},
},
};
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>;
},
// ...
},
},
};
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>;
},
// ...
},
},
};
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",
},
},
// ...
},
},
};
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,
},
},
// ...
},
},
};
No data selected