Building an admin dashboard in react-admin

This tutorial is going to walk through how to build a fully functional admin panel in react-admin with auth. To get the most out of this tutorial, you'll want to be comfortable with React and basic frontend/backend interaction.

React-admin is a framework that uses React, Material UI, React Router, Redux, and React-final-form to give you a unified admin framework that you can customize to fit your dashboard building needs. It’s developed and maintained by a dev shop called Marme Lab (I’m guessing they got tired of building the same admin UIs for their clients over and over again).

React-admin is a frontend framework, so it’s built to use your existing REST / GraphQL APIs. It allows you to easily create frontend admin applications that interact with your backend in a standardized way through data providers.

What are data providers, you say?

React-admin is unique in the way that it processes the interactions between your frontend and backend:

It uses something called an adapter approach (data providers): the data provider acts as the interface between the framework and your backend → it takes care of the querying and response handling between the frontend & your respective backend API(s) to allow you to focus on your dashboard building in modular steps.

To start, react-admin gives us data providers that can be used to backwards engineer our API’s if they haven’t already been built, or in the more likely scenario that they already exist, you can write your own data providers to interface with your existing APIs**.**

At a high level, react-admin offers some pretty interesting features (we’ll dive into one of them later):

Long story short: it’s a powerful framework.

Prerequisites:

Let’s start out by creating a new folder to store our codebase for our new admin app. I’m going to call mine react-admin-tutorial (very creative, I know). After dropping into your new directory, let’s create a new react application with create-react-app:

This will create a new empty React app that we can use to jumpstart our development through Facebook's create-react-app tool. Now we can move into the directory holding our new app:

That will install the react-admin package and the data provider we need to connect to our fake API. Our app will be running at localhost:3000. Now it’s time to work on building out the app.

Subscribe to the Retool monthly newsletter
Once a month, we send out top stories (like this one) along with Retool tutorials, templates, and product releases.

For this tutorial, we are going to use JSONPlaceholder - this is a fake REST API that we can use to develop our frontend with fake data. This way, we’ll be able to focus on the core of react-admin without worrying too much about writing custom data providers yet.

First off, replace src/app.js with the following to get us off the ground:

Now you should see something like the screenshot below; this is the default page you get when you supply react-admin with the data provider it expects.

Now we’ll bring in our first resource:

The Resource component allows us to tell react-admin that we’d like to fetch and display a resource with the name “users.” The dataprovider processes this and makes a request according to its interface – in this case to https://jsonplaceholder.typicode.com/users – and then displays that to the user using the ListGuesser component. This “list” prop tells react-admin to use ListGuesser to take whatever data the resource receives and make it’s best guest to format the initial data grid.

We’ll use this initial with all of our resources to generate some initial list code - it spits out its best guess to the console for us to use. Here’s what things should look like:

The guesser gets us 90% of the way there, but we want to customize the columns to have slightly more human-readable labels. Inspect the table element in your browser, and copy the Guessed List that you see in your console (inspect element → console). It should look something like this:

We’ll create a new component that overrides these suggestions. Create a folder called components in src and paste the copied code in a new file called users.js (src/components/users.js). It should look like this :

The list is the main component here, handling the majority of the work (pagination, etc.) but the actual rendering of the data is left to the DataGrid, which renders a table where each record has one of the child components / fields. These fields’ data is sourced based on the source name that you provide, which matches up with what is received by the dataprovider from the API.

While we’re here, let's refine this list a bit to show how you can customize it. Here’s what I am going to do:

The changed fields should look like this :

Now we’ll need to replace the ListGuesser with our new list in the Resource component. Head back to App.js, and add in a line up top to import our new UserList component:

Now replace ListGuesser in the List prop of our Resource with the UserList:

With those changes, we should have a more concise and usable view of the users resource:

It’s worth mentioning that you can replace any of the components inside the datagrid with your own, so if you want to create your own fields to suit your needs, just drop them in and make sure to include the source prop.

To show you what this would look like:

Paste this in src/components/CustomEmailField.js and modify the email field in src/Users.js to reflect our new custom field.

By swapping out the email fields, we customize the component that’ll render the email data record. As you can see above, we modified the original functionality to have the link be a mailto so you can click on it and open an email to the person. We also added an email icon with custom styles using useStyles.

Note: You can do plenty more in customizing the fields to your heart's desire that won’t be covered here, but this gives you a solid template to build off and create your own custom fields.

Let’s repeat this process with posts. There’s something else we need to tackle here: relationship handling. In our sample API, querying the posts resource gives us this JSON:

Notice how in each document there’s a userId attached. This userId allows us to create a reference between the user and the post within the admin panel, and thankfully react-admin automatically detects this for us.

To show the posts resource in our panel, let’s add another resource component:

Again, we’ll use the ListGuesser to generate the guessed fields. If you can see something like this (click on the “posts” tab), you should be in good shape.

We’re going to want to update these column names, so we’ll go through the same workflow as above. Go ahead and copy the code from the guessed list in the console and paste into a new file: src/components/posts.js.

It should look like this:

The ReferenceField component above allows us to create a relationship with the user resource. We identify the foreign key with the prop source=”userId” and create the relationship with the reference prop.

Also, make sure to change the list prop for the new posts resource to reference our custom PostList in App.js – import the PostList and then replace ListGuesser in the post resource’s list prop.

Note: I went ahead and changed the TextField, what is actually displayed for the reference inside the table, to display the name. You can display anything contained within a user object by passing the source name for the user resource. Logically speaking, any child of a reference field will be working with the record of the referenced resource. In this case, the user resource is referenced so the child textfield’s source will be derived from the user resource.

Next, we’re going to add an edit button to set us up to be able to modify content. We’ll start by adding a new component into our Datagrid: an EditButton at the bottom (and adding it into the import from react-admin up top).

Much like the list prop, we need to pass an edit prop to our resource in order to be able to have react-admin generate edit capabilities. We’ll use a component called EditGuesser and pass that to the posts resource in src/App.js (make sure to add it into the import up top):

This guesser will generate the initial edit code for the posts that we can then customize.

Once you have the edit guesser wired in, check that the edit functionality works by clicking edit on one of the post records. It should bring you to a screen where you can make edits to the fields of the object being modified – since we’re using a test api, changes made will not persist beyond the local frontend state. In a real application though, the edit functionality would interface with the backend to make the necessary changes as you make them to the objects on the frontend.

Once you verify this is working, take the guessed code from the console, and put it in src/components/posts.js. It should look something like this:

Note: you’ll have to import previously unused components – SimpleForm, TextInput, ReferenceInput, SelectInput, and Edit.

Let’s copy and paste the edit code now and create a CreatePost component. It takes almost the same structure of the edit component. Your posts.js file should like this:

The only difference between the edit and create components is that we’re using two different wrapper components – <Edit> and <Create> – which each handle the data processing & interfacing with the backend uniquely. Make sure to add the Create component into your import statement up top.

As you might expect, we need to supply the create prop in our resource too. Start by adding our two new components from posts.js into the import on top of App.js (PostEdit and PostCreate), and then add them into the posts resource:

While it’s not apparent in our code, react-admin bakes in a feature into our admin dashboard that enables deletion for every resource that has an edit component. If you check your edit screen on the Posts resource, you’ll see the delete button in the bottom right.

(Note that after clicking delete, the frontend will show that it was deleted due to optimistic rendering, but since our fake api disallows PUT/DELETE requests, this should error out after a few seconds. Not to worry though, once you’re hooked up to your live API, you’ll be fine.)

Although we only covered the basics with edit/create components, you can customize them even further with these props:

Also, if we want to create a rich input experience, we can customize the input fields with props like:

Let’s talk a bit about why react-admin is so fast. Optimistic rendering means that react-admin renders changes to the client side state before the server has returned with a response for a particular action. For example, if you deleted a user, react-admin will render the user as deleted before the request actually goes through and responds. In reality, react-admin puts an approximately 5 second delay on requests to resources initiated by the user. This allows for this kind of fast rendering and also the ability to undo actions.

Say you accidentally hit delete: you can undo your actions quickly with an undo button and react-admin will cancel the request to delete the user before even sending it to the server. Overall, optimistic rendering let’s the user experience a more seamless UX when compared to a more traditional model that waits for the server to return in order to render. That being said, there are obviously tradeoffs inherent in each model.

If you’ve been following along, you’ve seen that the List component is integral to building out an admin app with react-admin, so it’s worth understanding what’s going on behind the scenes. The lists acts as the data facilitator / processor / interface for the application’s data List components – i.e. the components that render resource data for, say, users in a list. All the children of that list can be thought of as dumb, as they are mainly presentational in nature, whereas the List itself handles the connection to the data and all the associated processes. For example, if you want to control a filter, pagination, or sorting, you need to deal with the <List> components of a parent component.

As your application grows (and maybe scope creep starts happening), being able to leverage these customizable capabilities becomes important to fit your needs.

Nobody wants their internal APIs to be publicly accessible, so let’s quickly run through how we’d add some authentication into our admin console. By default, react-admin has a login page ready and setup, but it’s authentication provider agnostic, meaning you can use whatever identity service you want with react-admin, assuming you write an authentication provider.

React-admin expects five methods from our authentication provider: login, logout, checkError, checkAuth, and getPermissions . We’ll add our own basic ones in. Let’s put them in a new directory and file, src/providers/authProvider.js:

Then go to your admin component in src/app.js and add the prop authProvider={authProvider}. Make sure to remember to add a new import statement for the authProvider component as well:

After that, you’ll have a functioning admin app with a login page. Granted, some of the services and backend still need to be wired up in a production app, but you’ve still accomplished a lot! The big thing to take away from this is that react-admin makes it insanely easy to interact with your existing data that sit behind existing APIs, as long as you can fulfill the data contracts between the data providers and the API services.

For now, let’s implement a real authentication service, firebase auth. First you’re going to need to install react-admin-firebase: this package is an authProvider built specifically for use with react-admin and firebase.

Next, you’ll need to go to firebase and create a new project, and then go to settings to retrieve your auth config. Once you have it, create an auth object in src/app.js like below below:

You’ll notice that the main piece is the firebase config, and beyond that you can set options and pass them as an optional argument to FireBaseAuthProvider. These options would allow you to customize the authentication handling, but we’ll leave it to the defaults for now.

This should set us up with a fully functioning login page. If we create a user in the firebase console with a username(email) and password then try to login to our admin app, we should be able to successfully get through.

You see the code for the final functioning app on GitHub.

React-admin lets us get off the ground and build a super functional admin app in minutes, not months. It abstracts the nasty building and maintaining that us developers are usually tasked with. But where do you go from here if you want keep building?

If you want to use your own API, react-admin’s tutorial is a must read. At a high level, this is what the dataProvider interface needs to look like:

The following is a list of existing data providers I got from marmelab.com (the developers and maintainers of react-admin):

Check these out to see if any fit your stack before you try and write your own. Many of these will allow you to jumpstart your dataprovider development, if not eliminate you having to write one.

I will say that what you need to do to write your dataprovider is highly dependent on your api schema. If it’s standard, it will probably either fall under one of the prebuilt data providers listed above, or be fairly easy to implement. But if your api isn’t as standard, it might take more than a few minutes to get the data provider working.

If you’re building an admin app or custom dashboard or for your organization, check out Retool! Retool saves you a bunch of time and hassle by letting you drag and drop components like tables, search boxes, and buttons, and connecting them to SQL or Javascript on the backend. You can also build off of templates to customize your dashboard with custom components that interface with your backend.