Skip to content
+

Build your first app

Learn the fundamentals of building with Toolpad by creating a small application.

This guide will walk you through the process of creating a small Toolpad application. You'll use the MUI X Data Grid component to display a list of dog breeds from the Dog API. When you click on the name of a breed, a random photo of the breed will be displayed using the Material UI Image component.

Purpose

This guide is intended to introduce you to the fundamentals of building with Toolpad. By the end, you should be able to:

  • set up a new Toolpad app
  • navigate through your workspace
  • design a page and connect its data

Prerequisites

Make sure to install Node.js on your system.

Building your first application

Create a new app

  1. Create a new application

    npx create-toolpad-app dog-app
    
  2. Start the development server

    cd dog-app
    npm run dev
    

    The Toolpad application editor opens automatically in your browser.

Assemble the UI

  1. Hover over the component library and drag a Data Grid component into the canvas. Now repeat the process and drag an Image component as well. When you're done, the canvas should look like this:
Toolpad editor

The Toolpad editor with components dragged

Fetch data

  1. Locate the + (create new) button in the queries explorer. Press it and choose REST API.
Choose REST API

The Add query menu

  1. We'll be using the dog API for this tutorial. Set

    https://dog.ceo/api/breeds/list/all
    

    as the URL. Click the Run button to inspect the result of this request, and expand the message object in the response. If all went well, it will look like this:

Fetch URL

The dog API response

  1. To transform the response according to our needs, we choose the Transform tab and enable the Transform response option. Write the JavaScript expression:

    return Object.entries(data.message);
    

    in the editor. Click Run again to verify the result.

Transform response

The dog API response transformed

  1. Click on Save to save the query, and then rename it to dogQuery by double clicking on it in the explorer.

Bind data to UI

  1. Next, we will bind this data to components on the page. Click the Data Grid component to select it.

  2. Find the rows property in the inspector. Notice that there's a small Bind button to its right. Properties with this button next to them can be bound to state available on the page:

Bind data

The bindable rows property

  1. Click the button to open the binding editor. On the left you'll see a list of all bindable state in the page and on the right there's a code editor that accepts any JavaScript expression.

  2. Use the dogQuery available in the scope as a binding expression.

    dogQuery.data;
    

    save the binding and close the binding editor.

dogQuery.data

The binding editor

  1. If all went well, the Data Grid will now display the data from our query:
Connected data

The data grid with bound data

Make the app interactive

  1. Now, we can make this app interactive by displaying a random image of the selected breed. We'll create another query which reacts to the selection inside the Data Grid component.

  2. Create another query of the REST API type and add a breed parameter in the Parameters section on the right:

Breed parameter

Editing imageQuery

  1. Click on the Bind button next to the breed parameter value, and add the following JavaScript expression in the binding editor:

    dataGrid.selection?.[0] ?? 'akita'
    

    This will use the selected value from the Data Grid, and default to the "akita" breed when no row has been selected.

Breed binding

Binding breed to the selected value

  1. Then bind the query URL to the following JavaScript expression:

    `https://dog.ceo/api/breed/${parameters.breed}/images/random`
    
URL binding

Binding the URL to a JavaScript expression

  1. Save the binding and close the binding editor. Save the query and exit the query editor.

  2. Rename the query to imageQuery by double clicking on it in the queries explorer.

  3. In the canvas select the Image component to view its properties in the inspector. Click on the Bind button next to the src prop to open the binding editor, and bind it to imageQuery.data.message.

Bind image src to Java

Binding the Image src to the query response

  1. Try selecting different rows in the data grid to see the image update to a random image of the selected breed.
Image changes based on selection

The image changing based on the selected row

Preview the app

  1. Click on the Preview button to see a preview of what your app will look like when deployed:
Preview of app

The preview of our application

  1. That's it! Feel free to browse through the rest of the documentation to know more about what you can do with Toolpad.