This page was made in Builder!

Using custom fields in Builder

Using custom fields in Builder allows you to attach all types of easy to update data to your models. This can be super helpful when you want to use data from Builder to determine your app's behavior, or render specific fields in a certain way. An example use case is adding page specific SEO attributes that you use to render the correct metadata for each of your pages. This guide will go over how to add custom fields to a model in Builder using SEO metadata as an example.

If you are not yet familiar with models in Builder, make sure to check out our guide on creating models before diving in to this tutorial.

Create the fields

From the /models page, select the model you want to edit, and add custom fields by choosing +NEW FIELD.

Give your new field a unique name, and choose it's type. There are many different types to choose from, which makes it easier for whoever is updating content to provide exactly what they need. It also makes it simple to add certain validations on that data. For our example, we will be adding the field "SEO Image" that we will use when rendering the page to add the proper SEO image meta tag, as well as a "Canonical Url" custom field.

Entering field values in the editor

The next step is to create a new content entry for whatever model we just added the custom fields to. In our example, we added it to our "Page" model, so we will go there and add a new entry. In your specific case it will be whichever model you added the custom fields to.

Head to the /content page and click +NEW ENTRY in the upper right hand corner. Select the content type that you added the custom fields to.

Once you are in the editor, select the OPTIONS tab and enter whatever values you like for the custom fields you added. In our example we want to add an image and a canonical url. Once we hit publish we can consume and use those custom fields on the front end however we choose.

Using field values in your code

Once we add the custom fields to our model and then add specific values to our content, we can then use those values however we want in our code. In our example, we need to query the Builder API to get our SEO image and Canonical URL fields. Note: An easy way to explore the data that is sent from our API is to head over to /api-explorer. There you can query the Builder API in various ways using your actual data.

// See specific guides for Gatsby and Next.js for more options
    contentLoaded={data => {
      if (!data) {
        location.href = '/404'
      } else {
        const { seoImage, canonicalUrl } = data;

Querying by field values

You can also filter content by using queries with your custom field values. This might be useful if you want to retrieve content that only has a certain custom attribute. Using our example, we might want to filter for only entries that have a certain Canonical URL. For mre information on how to use queries on your API calls, read the docs on the content API and the html API or in the options object of any JS SDK

Questions or comments?

Visit the Builder Forum

Visit our Github