Skip to main content

Getting started with presentation components

Learn how to use various components to present text, numeric, and graphic information in your classic app.

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The new app builder is the recommended way to build apps and where Retool focuses new development.

Retool provides a variety of componenets that help you display information, alerts, and statuses. These components include:

Demo

Features​

Key features of presentation components include:

  • Dynamic values using embedded expressions.
  • Event handlers to define interaction.
  • Customizeable styles.

Specify content options​

The Content section of the Inspector contains settings that control the content of the component, including:

  • Value.
  • Default value.
  • Indeterminate, which shows a loading state with unknown progress for Progress Bar and Progress Circle.
  • States, which defines the list of possible values for Alert and Status.
  • Add-ons, which provide additional informational elements such as tooltips or icons.

To set the possible values for Status and Tags, define an option list either manually or by dynamically mapping an array of data. The states for Alerts must be defined manually.

Configure user interaction​

Progress Bar, Progress Circle, Status, and Text do not support user interaction. Text does include a screen reader announcement setting in the Interaction section of the Inspector. For more information, refer to Announce content changes to screen readers.

Alert, Statistic, and Tags support user interaction. The Interaction section of the Inspector contains settings that control user interaction. Use event handlers to listen for and handle interactions with your components.

note

Event handlers for the Tags component apply to all tags shown. Retool does not support individual event handlers for each tag.

Alert has several options for user interaction. You can add an event handler that triggers when the user closes the Alert, or you can add a link—called an action—to the Alert that triggers when clicked. To do so, select the state that you want to change. Then click the Action add-on, and add an event handler.

Announce content changes to screen readers​

Screen readers do not announce changes to the Text component by default. If you use Text to display messages that appear or update while someone is working, such as a running list of form validation errors, you can have Retool announce the value each time it changes.

To enable announcements, select the Text component and set Screen reader announcements in the Interaction section of the Inspector. There are two announcement options:

  • Polite waits until the user pauses before announcing the value. Use this for most messages.
  • Assertive announces the value right away and interrupts whatever the screen reader is reading. Reserve this for messages the user must act on before continuing.

Announcements are most reliable when the component remains on the canvas and only its value changes. Keep the Text component visible and update its Value instead of hiding the component and showing it when a message appears.

Customize appearance​

You can customize the presentation of your component in the Spacing and Appearance sections of the Inspector.

All components have a Hidden setting, which you can dynamically control with a truthy value that evaluates to true or false. You can also control the hidden property for a component using the .setHidden() method from event handlers and JavaScript queries.

You can also create custom style rules using the Styles setting. Each component has different styles that you can configure, but common ones include colors, fonts, and text styles. Use app-level or organization-level themes to set these styles across all components.