Hooks reference

Reference for custom React hooks.

Retool provides a set of custom React hooks, which give your app access to certain information and actions on the Retool platform. These hooks are stored in your app's frontend/hooks directory.

To update your app to use a hook, describe what you want in a prompt, or call one manually.

useCurrentUser

useCurrentUser returns the user who is signed in to the app.

Value	Type	Description
user	Object or null	The current user. This value is null while the request is in progress, and null if the request fails. Learn more about the Current User object.
loading	Boolean	Whether the request is in progress.

Example: Show the user's name

function Greeting() {
  const { user, loading } = useCurrentUser()

  if (loading) return <p>Loading...</p>
  return <p>Welcome, {user?.firstName}</p>
}

User actions

The following hooks provide access to user and account actions.

useRetoolAccountAuth

useRetoolAccountAuth returns functions that act on the user's Retool account. It returns an object with the following function:

Function	Type	Description
logout	() => Promise<void>	Signs the user out of Retool. Redirects the user to the login page.

Sign-out button

function SignOutButton() {
  const { logout } = useRetoolAccountAuth()
  const [error, setError] = useState(null)

  return (
    <>
      <button onClick={() => logout().catch((err) => setError(err.message))}>
        Sign out
      </button>
      {error && <p>{error}</p>}
    </>
  )
}

useRetoolAppsAndFolders

useRetoolAppsAndFolders returns the apps and folders the current user can access. It uses the same permission check as the Retool homepage, so the user sees the same items in both places. Use it to build a custom landing page.

Value	Type	Description
data	Object or undefined	An object with an apps array and a folders array. This value is undefined until load succeeds.
loading	Boolean	Whether a request is in progress.
error	Error or null	The error from the most recent request. This value is null if the request succeeded or hasn't started.
load	() => Promise	Requests the apps and folders. The promise resolves with the same object that data holds. If the request fails, the promise resolves undefined and sets error instead of throwing.

Each item in apps has the following properties:

Property	Type	Description
id	String	The unique identifier.
name	String	The app name.
description	String or null	The app description.
shortlink	String or null	The app's short URL.
folderId	Number or null	The ID of the folder that contains the app.
protected	Boolean	Whether the app is protected.
isMobilePage	Boolean	Whether the app is a mobile app.
isModule	Boolean	Whether the app is a module.
synced	Boolean	Whether the app is synced.
accessLevel	String	The user's access level for the app.
createdAt	String	The date and time the app was created.
updatedAt	String	The date and time the app last changed.

Each item in folders has the following properties:

Property	Type	Description
id	Number	The unique identifier.
name	String	The folder name.
folderType	String	The folder type.
isSystemFolder	Boolean	Whether Retool created the folder automatically.
parentFolderId	Number or null	The ID of the parent folder.
accessLevel	String	The user's access level for the folder.
createdAt	String	The date and time the folder was created.
updatedAt	String	The date and time the folder last changed.

List the apps a user can open

function AppLauncher() {
  const { data, loading, error, load } = useRetoolAppsAndFolders()

  useEffect(() => {
    load()
  }, [load])

  if (loading) return <p>Loading...</p>
  if (error) return <p>{error.message}</p>

  return (
    <ul>
      {data?.apps.map((app) => (
        <li key={app.id}>{app.name}</li>
      ))}
    </ul>
  )
}

Limitations

The following limitations apply to hooks:

• useRetoolAppsAndFolders and useRetoolAccountAuth are not supported in embedded apps. The request fails.
• Hooks do not provide coverage for other user actions available in classic apps, such as logging in, resetting a password, or claiming an invitation.