🎄 Puck 0.17: React 19 and field enhancements →
DocsAPI ReferenceFieldsExternal

External

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

Interactive Demo
Example
data

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

ParamExampleTypeStatus
typetype: "external"”external”Required
fetchList()fetchList: async () => []FunctionRequired
filterFields{ "rating": { type: "number" } }Object-
getItemSummary()getItemSummary: async ({ title }) => titleFunction-
initialFilters{ "rating": 1 }Object-
initialQueryinitialQuery: "Hello, world"String-
mapProp()mapProp: async ({ title }) => titleFunction-
mapRow()mapRow: async ({ title }) => titleFunction-
placeholderplaceholder: "Select content"String-
renderFooter()renderFooter: (props) => <p>Hello</p>Function-
showSearchshowSearch: trueBoolean-

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.

ParamExampleType
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
data

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
data

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
data

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
data

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
data

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
data

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
data

No data selected

renderFooter(props)

Customize what will be displayed in the footer of the modal.

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" },
            ];
          },
          renderFooter: ({ items }) => (
            <b>Custom footer with {items.length} results</b>
          ),
        },
      },
      render: ({ data }) => {
        return <p>{data || "No data selected"}</p>;
      },
      // ...
    },
  },
};
Interactive Demo
Example
data

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
data

No data selected

CustomNumber