Made in Builder

Made in Builder

Webinar 👉 Visually Build at Scale with Builder.io & Netlify on 12/1

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

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

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:

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:

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:

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.

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:

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.

friendlyName

string

The name the Visual Editor displays for the input.

helperText

string

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

model

string

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

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.

regex

object

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

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:

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.

localized

boolean

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

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.

color

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

date

Takes same formats as the date constructor for Javascript.

email

Creates an email value for a component.

file

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

list

A collection of items.

Alias: array

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.

longText

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

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

number

Specifies that an input field expects a number.

object

A set of specific names and values.

Tip: object requires thedefaultValue option.

richText

Displays a rich text editor and provides the value as HTML

Alias: html

string

Any text, usually short in length and unformatted.

Alias: text

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:

Next steps

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


Need Expert help?

Reach out to us, and we will match you with a Builder expert.

Connect with us

Was this article helpful?