Custom Fields

A field in Builder is a piece of data on a model. For example, the built-in Page model comes with two fields, a Title and a Description. These two fields help define what a Page is. Any time you make or edit any kind of model in Builder, you have the option of editing fields or adding custom fields.

The following video shows some example custom fields on the three kinds of models in Builder: the Page, Section, and Data models.

Prerequisites

To get the most out of this document, make sure you've integrated Pages, Sections, or Data. The following tutorials give step-by-step instructions:

Integrate page building

Integrate section building

Integrate CMS data

Overview of custom fields

Custom fields are fields that you add to a model. You can add custom fields to models you create or to an existing model, such as the built-in Page model. All kinds of Builder models accept custom fields, so you can add the fields you need to Page models, Section models, and Data models.

Examples of custom fields include data such as title, URL, name, timestamp, or any piece of data you want to define on a model. You define and specify aspects of your custom fields such as:

Type: There are many types available in Builder. Refer to Custom field types for more detail.
Localization: Translate fields according to region settings.
Default value: Pre-populate the custom fields you create.
Helper text: Give your users a helpful hint about what to enter into the field.
Required: Make a field required or optional.
Enum: Give users a predefined list of options.
Hidden: Make a given field hidden when editing content.

The following video shows where to find custom fields on a model, points out the available field Types, and then shows Page and Section custom fields in the Visual Editor's Option tab.

Adding custom fields to a model

You can add custom fields to any model in Builder by doing the following:

Open the Model.
Click the Edit Fields button.
Click + New Field.
Name the field.
Choose a Type.
Configure any other settings for the field and add additional fields as needed.
Scroll to the top and click Save.

The following video shows adding a custom field called name and date to a model.

For Pages and Sections, the custom fields you create display in the content entry on the Options tab as in the following image.

For Data, the custom fields you create on the Data model are available in the Data entry. For example, a hypothetical Blog Author Data model has three custom fields, Name, Photo, and URL. The following video shows the custom fields on the Data model and using those fields in a Data entry for a new Blog Author.

To delete a custom field, click the x to the right of the field.

Using field values in your code

When you have custom fields on your model you can add specific values to the content and use those values however you want in your code. This example queries the Builder API to get the SEO image and a Canonical URL fields.

Tip: To interactively explore the data that is sent from the Builder API, check out the Builder API Explorer where you can query the Builder API using your actual data.

import { BuilderComponent, builder } from '@builder.io/react'

export const getStaticProps = async () => {
  const page = await builder.get('page', ...);
  return { props: { page } }
}

export default ({ page }) => {
  return ( 
    <MyLayout seoImage={page.data.seoImage} canonicalUrl={page.data.canonicalUrl}>
      // Your layout component that you pass in the custom fields
     <MyLayoutComponent showNavigation={page.data.showNavigation} layoutWidth={page.data.layoutWidth}>
       // Render the rest of the Builder page content
       <BuilderComponent model="page" content={page} />
     </MyLayoutComponent>
    </MyLayout>
  )
}

Querying by field values

You can also filter content by using queries with your custom field values. This technique is useful if you want to retrieve content that only has a certain custom attribute. For example, you could filter for only entries that have a certain Canonical URL. For more information on how to use queries on your API calls, refer to Content API and the HTML API or in the options object of any JS SDK.