Input Types in Builder

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:

Required inputs: inputs you must use with your custom components
Optional inputs for further customization: inputs that you can use to modify the look and behavior of your component in the Visual Editor
Input type examples: definitions, code snippets, and a screenshot of input types in the Visual Editor

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.

Prerequisites

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

Required inputs

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

Name Required Description

Name	Required	Description
`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`

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

Optional inputs for further customization

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

Name	Type	Description
`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 with `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. For versions of `@builder.io/react` prior to `4.0.3` and Gen 2 SDKs for all Gen 2 packages prior to `2.0.3`, if you use `showIf` in `subFields`, you must pass the value as a string, for example: subFields: [ { ... showIf: 'true' // or showIf: `options.get('someField') === 'someValue'` } ] In versions `4.0.3+` of `@builder.io/react` and `2.0.3+` of Gen 2 SDKs, `showIf` can be a function for `subFields`.
`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, }`

Input type examples

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.

`boolean`

An input field taking true or false.

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

`color`

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

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

`date`

Takes same formats as the date constructor for Javascript.

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

`email`

Creates an email value for a component.

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

`file`

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

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

`list`

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.

`localized text`

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,
}

`longText`

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.

`number`

Specifies that an input field expects a number.

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

`object`

A set of specific names and values.

  {
      name: 'Carousel',
      type: 'object',
      defaultValue: {
        // Provide default value here,
        // NOT in the subFields
         text: 'This is the default text input',
         url: 'http://www.myexampleurl',
         variant: 'primary'
      },
      subFields: [
        {
          name: 'text',
          type: 'string',
          required: true,
        },
        {
          name: 'url',
          type: 'url',
          required: true,
        },
        {
          name: 'variant',
          type: 'string',
          enum: ['primary', 'info', 'dark', 'light', 'warning'],
        },
      ],
    }

If you have large objects with multiple fields:

Use folded so that multiple inputs are collapsed by default 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',
      subFields: [
        ... /* Lots of subFields here */
      ] 
    },

Screenshot of an example object a folded property set to true.

Tip: object requires thedefaultValue option. Additionally, if you want to specify default values, make sure you provide them at the object level, not in the subFields.

`richText`

Displays a rich text editor and provides the value as HTML

Alias: html

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

`string`

Any text, usually short in length and unformatted.

Alias: text

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

`Tags`

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

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

An example using icons

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' ..] }]
  },

What's next

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

Was this article helpful?