Assemble components

Components are one of the fundamental building blocks of Retool. They function similar to React components as you can pass properties and they have internal state. You can combine Retool's library of components with your data to build interactive apps.

Some commonly used components include:

• Table: A table of data that can be sorted, filtered, paginated, and downloaded in CSV format.
• Form: Group input fields in a form and submit them together.
• Select input: A combination Select and input field to select a value or directly enter as text.
• Chart: Visualize data as charts and graphs.

Adding, editing, and deleting components

Adding a new component to your Retool app is as simple as opening up the Components tab in the right panel, selecting a component from the list, and dragging the component where you want into the editor grid (the canvas). You can always bring up the components list by clicking on a blank area of the canvas.

Editing is best done from the Inspector tab in the right pane. To open the Inspector tab, click on the component you want to edit. From here you’ll be able to change your component’s name as well as edit its properties like its text, color, or on-click handler (for more information on component properties, keep reading!). You can also resize your component by clicking on it and dragging it by one of its corners.

To delete a component, select it by clicking on it and press the delete icon in the Inspector tab of the right pane (or press the Delete key on your keyboard while your component is selected).

Component properties

It’s useful to think of Retool components as being backed by a simple JavaScript object. Every component has a name (like a variable name e.g. table1) and its corresponding object, which might have properties like label for a Checkbox or imageUrl for an Image component.

The values of these properties can be static (e.g. the string “Submit a new claim” - often used for titles, labels and instructional text blocks) or dynamic (e.g. Hello {{current_user.firstName}} - for when you want to change how or what is displayed based on inputs). Dynamic values are always wrapped in double curly braces {{}}, which evaluate to JavaScript.

Some useful and common dynamic property values:

• Data returned by a query (eg. {{usersQuery.data}})
• A property of another component (eg. {{ allUsersTable.selectedRow.data.first_name }})
• Functions (eg. {{ sumAllUsers.value }})
• JavaScript (eg. {{ [1,2,3].map(x => x + 1) }})

👍

Tip: use JavaScript between the braces. Get pre-installed libraries.

When you use {{ textinput.value }}; the code you have inside the curly braces is executed as JavaScript. So if you want to conditionally change the Text depending on whether or not it's defined, you can use {{ textinput1.value ? textinput1.value : 'Not checked' }}.

We also give you _ (lodash docs) and moment (moment docs) already installed. Try {{ moment.now() }} or {{ _.snakeCase('Foo Bar') }} in a Text component.

The best part is a component’s properties are available globally in the scope of your app - any component can access and change any other component’s properties!

To demonstrate why this is useful, lets build a simple app that dynamically shows and hides an image based on a toggle.

First drag on a Toggle component followed by an Image component.

Next, select the Image component and in the right pane set its “Hide when true” property to refer to your toggle’s value: {{toggle1.value}}

🚧

Our autocomplete has access to all the attributes inside a component. If you're accessing an object and autocomplete isn't working, that means the value isn't there and can't be used.

For example: typing textinput1. will give you suggestions for all the attributes found inside textinput1, including its .value. But if you type textInput1., you won't see anything, since textInput1 is not a valid object (the casing is wrong).

Finally, flip the toggle - your cat should disappear (unfortunately)!

Your image’s “hidden” property is now dynamically set based on your toggle’s value. You can see this in action by opening up the left pane (⌘B) and expanding image1 in components. As you flip the toggle, you should see hidden flip from false to true.

👍

Tip: the left pane is your friend!

The left pane contains all the properties for each component, their current values, queries and even global variables like url params or the current user. It is a valuable tool for helping figure out why something isn't working as you intend.

Try adding some other components to your editor and using the left panel to see which properties are available to you (e.g. Table’s selectedRow.data or Bar Chart’s datasets).

Can’t find the component you’re looking for?

If Retool's built-in components don't meet your needs, you can set the html value of a Text component to true and then pass custom HTML, CSS, and JavaScript to it. This approach may be good enough if you just need custom content, styles, or behavior for that one particular component. If you need your custom component to interact with the rest of your app, you can build your own custom component using React or pure JavaScript.

Armed with this knowledge you can now unlock a trove of amazing uses for Retool - for a little bit of inspiration, check out our templates.