Working with components

Components are the building blocks of Retool.

Components are one of the fundamental building blocks of Retool. Think of them as React components: they consume props, and have internal state. Retool gives you a library of components which you combine with your data. String together a bunch of interacting components and you've got yourself a tool.

Common component types

Here are some common component types that can get you started with building powerful Retool applications.

  • Tables - view and interact with your data whether it comes from a database, API or elsewhere!
  • Forms - build powerful flows to input, validate and submit data
  • Input/Selection Types - change your UI based on user interaction (filtering, typeahead, etc.)
  • Modals - add popups to display information, warnings or confirmations to the user
  • Charts - visualize complex data in an aesthetically pleasing way
  • Images - display images, logos, or profile pictures (we support Base64!)

These are a few examples, but there are a bunch more Retool components you can use. You can find a full catalog of components and a reference of their properties and methods on our interactive Components Reference page.

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

🚧

Warning: if it's not autocompleted, it won't work.

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.

Updated 5 months ago


What's Next

Now you understand components, let's connect them to queries, so you can pull in your own data.

Reading and Writing Data

Working with components


Components are the building blocks of Retool.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.