Made in Builder.io

Join us for the biggest Figma-to-code launch of the year

Builder.io logo
Talk to Us
Platform
Developers
Talk to Us

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

When you create custom components to use in Builder, there are two required inputs and a number of optional inputs to help you further customize your components. This document covers these inputs types in detail.

This document covers the following:

Tip: With plugins in Builder, you can create custom field types. For more information on using Builder's built-in plugins or creating your own, see Intro to Built-in Plugins and Making a Plugin.

To get the most out of this document, you should be familiar with Integrating Your Custom Components with Builder.

When you register a component with Builder, you must include the name and type inputs as in the following table:

NameRequiredDescription

name

Yes

A unique name for this input that should match the equivalent prop name on your React component.

type

Yes

Types correlate to what editing UI is appropriate to edit this field. Common types include:

'string'
'number'
'boolean'
'longText' // String type but with a multiline text field editor
'richText' // Displays a rich text editor and provides the value as html
'file' // Uploads a file and provides the value as a url string
'color'
'date'
'email'
'object'
'list'
'reference' // displays a content entry picker to reference

You can use additional inputs to further customize your components in Builder. The following table contains Builder's optional inputs.

NameTypeDescription

advanced

Boolean

Set to true to put this component under the Show More section of the Options tab. Useful for things that are advanced or rarely used and don't need to be prominent.

allowedFileTypes

array

For the file input type, specify what types of files users can upload. This is an array that takes content-type files such as:

allowedFileTypes: ['jpeg', 'png', 'mp4', 'gif', 'pdf', 'svg']

defaultValue

any

Use for showing an example value in the input form when creating a new instance of this component, to users understand its purpose.

enum

array

For any text-based field type, you can specify a set of options that the field can use.

enum: ['option 1', 'option 2']

friendlyName

string

The name the Visual Editor displays for the input.

friendlyName: 'Open link in new tab',

helperText

string

Provide text to help the end user know how to fill in this input. Displays below the input.

helperText: 'Some helpful description about how to use this input'

model

string

Use optionally with inputs of type reference. Restricts the content entry picker to a specific model by name.

Builder.registerComponent(ProductBox, {
  name: 'ProductBox',
  inputs: [{
    name: 'metafields',
    type: 'reference',
    model: 'product-metafields'
 }]
})

onChange

Function

Provide a function that is called whenever the value of the input is updated. Useful for more complex validation than regex or running custom logic when an input value updates.

// Example of how to validate and limit the length 
// of a list input called myList
// 
// Note: the function is stringified and evaluated in 
// the context of the parent window, 
// so don’t try to use any references to other 
// variables or functions that you might have 
// within the file that your component defined
onChange: (options) => {
  if (options.get('myList').length > 6) {
    options.set('myList', options.get('myList').slice(0, 6))
    alert('maximum items is 6, delete items to continue')
  }
}

regex

object

For any input that results in a string value you can provide a regex to validate user input.

 regex: {
    // pattern to test; such as "^\/[a-z]$" 
    pattern: "^\/[a-z]$",
    // flags for the RegExp constructor; for example, "gi"  */
    options: "g",
    // message to display to end-users if the regex fails
    message: "You must use a relative url starting with '/...' "
  }

showIf

Function

Show and hide the input dynamically.

  • options is an object with the current options, that is, values from inputs, that are set on the component.
  • parent is the component definition,
  • parentElements is an array of all the parent elements of where the component is placed

For example, to only show the input if the component is inside of a Columns component has the input myInputOption set to true, you could write a function as follows:

showIf: (options, parent, parentElements) => {
  return options.get('myInputOption') 
    && parentElements.some(el => 
      el && el.component && el.component.name === 'Columns');
}

Use the state of other inputs via options to hide or show inputs that depend on one another. For example, you could show an input that opens a link in a new tab only if a link is present, instead of always showing all inputs.

subFields

Input[]

If the input type is list , you must include the subFields property that is a list of inputs, with this same schema, for each list item.

{
      name: 'reviews',
      type: 'list',
      defaultValue: [ 
            { reviewText: 'hello' 
     }],
      subFields: [
	{
          name: 'reviewText',
          type: 'string',
          defaultValue: '"You are 
          the best"',
        },
        {
          name: 'reviewAuthor',
          type: 'string',
          defaultValue: 'Jane Smith',
        },
        {
          name: 'image',
          type: 'file',
          allowedFileTypes: ['jpeg', 'jpg', 'png', 'svg'],
          required: true,
          defaultValue:
         'https://cdn.builder.io/api/v1/image/assets%2Fpwgjf0RoYWbdnJSbpBAjXNRMe9F2%2Ffb27a7c790324294af8be1c35fe30f4d',
        },
      ],
    }

localized

boolean

You can mark any input type with localized to get a separate value for each of the locales configured on your space.

{
  name: 'title',
  type: 'text',
  localized: true,
}

This section provides examples of the effects of input types in Builder and covers the following:

  • Input type name
  • Definition of input type
  • Alias/alternative input type you can use instead of the given input type
  • Screenshot of input type's effect in Builder's Visual Editor

Tip: This section covers the built-in types for custom components, but you can also make your own with plugins. For more information, see Making Your Own Plugins Overview.

An input field taking true or false.

  {
    name: 'darkMode',
    type: 'boolean',
    defaultValue: true,
  }

Provides a color value, in hex or rgb, to a component.

 {
    name: 'backgroundColor',
    type: 'color',
    defaultValue: '#fafafafa',
  }

Takes same formats as the date constructor for Javascript.

  {
    name: 'event',
    type: 'date',
    defaultValue: 'December 17, 1995 03:24:00', 
  }

Creates an email value for a component.

  {
    name: 'signup',
    type: 'email',
    defaultValue: 'noreply@email.com'
  }

Uploads a file and provides the value as a URL string. Refer to allowedFileTypes for details.

  { 
    name: 'image',
    type: 'file', 
    allowedFileTypes: ['jpeg', 'png'] 
  }

A collection of items.

Alias: array

{
      name: 'reviews',
      type: 'list',
      defaultValue: [ 
            { reviewText: 'hello' 
     }],
      subFields: [
	{
          name: 'reviewText',
          type: 'string',
          defaultValue: '"You are 
          the best"',
        },
        {
          name: 'reviewAuthor',
          type: 'string',
          defaultValue: 'Jane Smith',
        },
        {
          name: 'image',
          type: 'file',
          allowedFileTypes: ['jpeg', 'jpg', 'png', 'svg'],
          required: true,
          defaultValue:
         'https://cdn.builder.io/api/v1/image/assets%2Fpwgjf0RoYWbdnJSbpBAjXNRMe9F2%2Ffb27a7c790324294af8be1c35fe30f4d',
        },
      ],
    }

Tip: list requires the defaultValue option.

A localized text input is a key/value object where the keys are the locales configured in your space. For more information, see Introduction to Localization with Builder.

{
  name: 'title',
  type: 'text',
  localized: true,
}

Same as string type but with a multi-line text field editor.

  {
    name: 'description',
    type: 'longText',
    defaultValue: 'Builder is the first and only headless CMS with a powerful 
    drag-and-drop visual editor that lets you build, 
    optimize, and measure digital experiences with speed and flexibility'
  }

Tip: If the text is to be formatted, use richText.

Specifies that an input field expects a number.

  {
    name: 'amount',
    type: 'number',
    defaultValue: 20,
  }

A set of specific names and values.

  {
      name: 'Carousel',
      type: 'object',
      defaultValue: {
         variant: 'primary'
      },
      subFields: [
        {
          name: 'text',
          type: 'string',
          required: true,
        },
        {
          name: 'url',
          type: 'url',
          required: true,
        },
        {
          name: 'variant',
          type: 'string',
          defaultValue: 'primary',
          enum: ['primary', 'info', 'dark', 'light', 'warning'],
        },
      ],
    }

If you have large objects with multiple fields:

  • Use folded so that multiple inputs are rendered collapsed to preserve space on the screen.
  • Use keysHelperText to provide helpful copy to the user.
    {
      name: 'HugeObject',
      type: 'object',
      folded: true,
      keysHelperText: 'Pick a property to edit',
      helperText: 'Edit this enormous object',
      // Example of 30 subfields
      subFields: Array.from({ length: 30 }).map((_, index) => {
        return {
          // Type can be whatever you need
          type: index % 2 === 0 ? 'text' : 'file',
          allowedFileTypes: ['jpeg', 'jpg', 'png', 'svg'],
          name: `prop${index}`,
          helperText: `The helper text of prop ${index}`,
        }
      })
    },
Screenshot of an example object a folded property set to true.

Tip: object requires thedefaultValue option.

Displays a rich text editor and provides the value as HTML

Alias: html

  {
    name: 'description',
    type: 'richText',
    defaultValue: '<b>This text is bold</b>'
  }

Any text, usually short in length and unformatted.

Alias: text

  {
    name: 'buttonText',
    type: 'string',
    defaultValue: 'Click',
  }

Tags, usually short text for adding tags to your content entries.

  {
    name: 'blogTags',
    type: 'Tags'
  }

If you have a design system that features an icon set, you can use a custom component that takes an icon name as input. In this way, you can manage and distribute your icons across your app. Register your icon component as below:

 Builder.registerComponent(Icon, {
    name: 'Icon',
    inputs: [{ name: 'icon', type: 'text', enum: ['error', 'warning' ..] }]
  },

Every use case is unique. If you need further customization, you can add custom types with plugins.


Looking to hire a third party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Get the latest from Builder.io

Newsletter

Developer Newsletter

Latest tips, tricks, and news for frontend developers from our blog

Product Newsletter

Latest features and updates on the Builder.io platform

By submitting, you agree to our Privacy Policy