Components

Learn about Retool's UI components.

Components are the fundamental building blocks of Retool apps. They are prebuilt interface elements to display data, and manipulate or interact with it based on user actions. Refer to the Retool Component Library to browse available components and view reference documentation.

How components work

You drag and drop components in the App editor to assemble your app's interface, then configure them to interact with data, perform actions, or render content. Any changes you make to the component's state in the App editor or by interacting with the component are immediately reflected.

Component model

Retool's components are functionally similar to React components. They are designed to be modular and reusable, and have internal state. Each component is represented by a JavaScript object that contains all of its properties and their current values. The following is an example of a Text Input component:

{
  "pluginType": "TextInputWidget2",
  "spellCheck": false,
  "readOnly": false,
  "iconAfter": "",
  "showCharacterCount": false,
  "autoComplete": false,
  "maxLength": null,
  "hidden": false,
  "customValidation": "",
  "patternType": "",
  "hideValidationMessage": false,
  "textBefore": "",
  "value": "Jenny Rosen",
  "_validate": false,
  "required": false,
  "disabled": false,
  "minLength": null,
  "pattern": "",
  "validationMessage": "",
  "textAfter": "",
  "showInEditor": false,
  "showClear": false,
  "tooltipText": "",
  "labelAlign": "left",
  "id": "textInput1",
  "formDataKey": "textInput1",
  "labelCaption": "Enter your username",
  "labelWidth": 33,
  "autoFill": "",
  "placeholder": "Enter value",
  "label": "Username",
  "labelWidthUnit": "%",
  "invalid": false,
  "iconBefore": "",
  "inputTooltip": "",
  "autoCapitalize": "none",
  "loading": false,
  "labelPosition": "left",
  "labelWrap": false,
  "maintainSpaceWhenHidden": false
}

Similar components often share characteristics, allowing you to switch a component from one to another with little to no change. This makes it possible to switch components as your needs grow without having to rebuild your UI from scratch.

Switch component

Configuration and properties

You can write JavaScript almost anywhere in Retool using {{ }} and component property values are available globally. This makes it possible to reference other properties when configuring a value.

For example, you can configure a Text component to display the value of a Text Input component with {{ textInput1.value }} in the App editor. This also makes it possible to control behavior through truthy or falsy values. You can use expressions like a ternary operator to use different values based on a condition, such as the value of a Checkbox component.

Events

Many components trigger events based on certain user interactions, such as clicking a button or selecting a value. Event handling enables you to trigger queries or perform actions based on the type of event.

Retool's approach with components makes it possible for you to build complex UIs that reflect changes immediately and dynamically adjust based on any conditions you need.

Configure a click event handler for a Button component

Methods

The majority of components include JavaScript methods that control their behavior. Component methods make it possible to write complex JavaScript statements to interact with components and change their state in ways that cannot be achieved with references or inline JavaScript using {{ }}.

Similar components often share the same methods. For example, setValue() is commonly supported by most inputs as a method to set the value of the component.

textInput1.setValue("Hello World");

Presets

A preset is a preconfigured version of an existing component. Retool's component library includes a number of presets for commonly used configurations. For instance, the URL component is a Text Input component that is preconfigured with URL pattern matching and prefix text. The URL component has the same internal state as Text Input, but configured for URL inputs.

Custom components

If you have a use case that isn't handled by Retool's built-in components, you can build your own custom component using HTML, CSS, JavaScript, and React. Custom components are complex but enable you to develop a component that meets your exact needs.