Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

Input types

Builder's input types define the editing interface for fields in both custom components and data models.

Use input types in two main contexts:

  • Custom components: When registering components with Builder.registerComponent()
  • Data models: When creating custom fields for your content models

Most input types work identically in both contexts, though some features like showIf and onChange are specific to data models, and the model input type is only available for data models.

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 Overview of built-in plugins and Build a custom plugin.

Prerequisites

To get the most out of this document, you should be familiar with Register custom components with Builder.

Required inputs

When you register a component with Builder, you must include the name and type inputs.

name

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

type

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

'boolean', 'color', 'date', 'enum', 'email', 'file', // Uploads a file and provides the value as a url string 'list', 'string', 'longText', // String type but with a multiline text field editor 'number', 'object', 'reference', // Displays a content entry picker to reference 'richText', // Displays a rich text editor and provides the value as html 'Tags', // Add multiple short strings in an array 'url', // Adds URL pattern requirements 'model', // Use a model's defined schema as inputs 'code', 'json', 'javascript'

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.

advanced

Type: Boolean

Description: 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

Type: array

Description: 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

Type: any

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

enum

Type: array

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

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

Instead of a string, pass an object to customize the displayed label and internal value. This is useful if you are using code to modify state within your content entry.

enum: [ { label: "option 1", value: "opt-1", }, { label: "option 2", value: "opt-2", } ]

friendlyName

Type: string

Description: The name the Visual Editor displays for the input.

friendlyName: 'Open link in new tab',

helperText

Type: string

Description: 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

Type: string

Description: 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

Type: Function

Description: 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

Type: object

Description: 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

Type: Function

Description: 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

Type: Input[]

Description: 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

Type: boolean

Description: 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 Intro to Plugins.

boolean

An input field taking true or false.

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

code

A code editor with syntax highlighting and language selection. Supports multiple programming languages including JavaScript, CSS, HTML, and others.

{ name: 'customScript', type: 'code', defaultValue: 'console.log("Hello World");' }

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

enum

Creates a dropdown of the given values. The label is what is shown during option selection while the value is what can be accessed within code upon selection.

{ type: "enum", name: "sortBy", enum: [ { label: "Date of Creation", value: "CREATED_AT", }, { label: "Location ID", value: "ID", }, { label: "Popularity", value: "POPULARITY", }, ], }

file

Uploads a file to the Organize with the Asset Library and returns the value as a URL string. Refer to allowedFileTypes for details.

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

If the uploaded file includes alt text in the Asset Library, Builder provides an altText prop to the custom component without requiring manual configuration.

To override the default alt text, register a separate input, as shown in the example:

{ name: 'image', type: 'file', allowedFileTypes: ['jpeg','gif'], }, /* Define altText manually */ { name: 'altText', type: 'string', }

javascript

Custom JavaScript code snippets with syntax highlighting optimized for JavaScript.

{ name: 'eventHandler', type: 'javascript', defaultValue: 'function handleClick() { /* your code */ }' }

json

Free-form JSON input with validation and syntax highlighting.

{ name: 'config', type: 'json', defaultValue: '{"theme": "dark", "enabled": true}' }

list

A collection of items.

Requires the defaultValue option.

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

copyOnAdd

Type: boolean

Required: To use copyOnAdd, you must use it with list. See example below.

Description: Configurable option onlist input types. When set to false, newly added list items start empty instead of copying the previous item's values. Defaults to true.

name: "ProductGrid", inputs: [ { name: "products", type: "list", // Use list defaultValue: [], copyOnAdd: false, // New items start empty instead of copying previous item's values subFields: [ { name: "title", type: "string", }, { name: "image", type: "file", allowedFileTypes: ["jpeg", "jpg", "png", "webp"], }, ], }, ]

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 you need to users to format the text, use richText.

model

Gets fields from another data model and stores the data at the content level, rather than creating a reference.

Unlike the reference type, which links to another content entry, the model type copies the structure from another model to store data locally within the current content entry.

This input type is primarily used in Data models rather than custom components.

{ name: 'authorInfo', type: 'model', model: 'author', // References the 'author' data model }

number

Specifies that an input field expects a number.

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

object

A set of specific names and values.

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

{ 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.

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

url

A valid URL. URLs must be absolute (start with http:, https:, mailto:, sms:, or tel: and have a hostname) or site relative (/page/name) or a hash (#something).

{ name: 'myUrl', type: 'url', defaultValue: 'https://builder.io', }

Input types for data models

While most input types work identically in both custom components and data models, some types and features are specific to data model usage.

Model-specific input types

  • model: Available only in data models for embedding another model's structure
  • reference: Creates relationships between different content entries

Advanced features for data models

Data model inputs support additional configuration options:

showIf conditional display

Control when fields appear based on other field values:

{ name: 'advancedOptions', type: 'object', showIf: function(options) { return options.get('enableAdvanced') === true; }, subFields: [...] }

Important: showIf hides fields in the UI but doesn't remove their values from the content. Fields hidden by showIf still return their values in API responses.

onChange event handling

Execute custom logic when field values change:

{ name: 'quantity', type: 'number', onChange: function(options) { const value = options.get('quantity'); if (value > 100) { // Handle edge case } } }

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?