White Label the Payload CMS Admin UI

Easily make Payload the perfect white labeled headless CMS. With Payload, you get complete control of the look and feel of the Admin Panel.

Across the Admin UI, the branding from Payload is minimal so that the focus stays where it should be—on your application. By updating the Payload branding, you can create a customized interface and your client (or team, or whoever will access your admin panel) will be greeted with a dynamic interface that is consistent with your application branding.

In this blog post, you will learn how to rebrand and white label the Payload admin panel for your application by modifying the following elements:

• Favicon
• Title
• ogImage
• Icon
• Logo

Get Started

You can use your own Payload app or start a new one for this tutorial. If you haven't started a project yet, you can get set up easily by running npx create-payload-app in your terminal.

For more details on how to start an application, including how to do so from scratch, read the installation documentation.

Payload Config

Start by navigating to your base Payload config file in which all options for the Admin panel are defined.

Below is an example config file:

import { buildConfig } from 'payload/config';
import dotenv from 'dotenv';
import Page from './collections/Page';
import Media from './collections/Media';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  collections: [
    Page,
    Media,
  ],
});

Admin Option

Next, add the admin option to your payload config file this can start as an empty object.

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {}, // Add this
  collections: [
    Page,
    Media,
  ],
});

Meta

The admin property takes the following sub-properties:

titleSuffix: Text that appends the meta/page title displayed in the browser tab—must be a string.

favicon: Image that will be displayed as the tab icon.

ogImage: Image that will appear in the preview when you share links to your admin panel online and through social media.

Now, let’s add the meta-object and the above properties.

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {
  // Add these properties
    meta: {
      titleSuffix: '- TRBL Design',
      favicon: '/assets/favicon.svg',
      ogImage: '/assets/logo.svg',
    },
  },
  collections: [
    Page,
    Media,
  ],
});

Serving Images

We need to ensure the images are served somewhere they can be downloaded by the browser. We could have saved an absolute URL if the assets
are hosted somewhere. Instead of that we set relative paths to an assets folder for favicon.svg and logo.svg above;
we can serve them from the same express app as Payload is using. Create a directory called assets and save your images there.

Then in your server.js or wherever you have defined express routes, add the line that serves /assets with express.static:

import express from 'express';
import path from 'path';

const app = express();
// Add /assets
app.use('/assets', express.static(path.resolve(__dirname, '../assets')));

payload.init({
  secret: process.env.PAYLOAD_SECRET_KEY,
  mongoURL: process.env.MONGO_URL,
  express: app,
  license: process.env.PAYLOAD_LICENSE_KEY,
});

app.listen(process.env.PORT);

Note: Anything in that assets folder will be publicly available when your app is hosted online.

At this point, if we check out our app in the browser—the tab will display your updated favicon and title suffix.

To test that the ogImage has successfully updated, use the browser inspector to view the metadata or test your app through your social media of choice or a web developer tool e.g. Twitter’s Card Validator.

Custom Components

In addition to metadata, the admin option also takes custom components to override the default configuration.

The properties we are interested in for rebranding the admin panel are:

graphics.Logo: Image component to be displayed as the logo on the Sign Up / Login view.

graphics.Icon: Image component displayed above the Nav in the admin panel, often a condensed version of a full logo.

Now let's set up these custom components:

• Add components and open an object
• Within components, add the graphics property and open another object
• Now we can point to the relevant files for the Logo and Icon

import Logo from './graphics/Logo';
import Icon from './graphics/Icon';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {
     meta: {
       titleSuffix: '- Custom Title',
       favicon: '/favicon.svg',
       ogImage: '/logo.svg',
     },
     // Add components
     components: {
       graphics: {
         Logo,
         Icon,
       },
     },
  },
  collections: [
    Page,
    Media,
  ],
});

These graphics need to be React components that can render whatever you'd like. They could render img tags or full React SVGs. In this example, we're going to include images, css and other html too.

import React from 'react';
import './logo.scss';

export const Logo = () => (
  <div className="logo">
    <img
      src="/assets/logo.png"
      alt="TRBL Design Logo"
    />
  </div>
);

Optionally we can include some styling too.

.logo {
  img {
    max-height: 200px;
    margin: auto;
  }

  h1 {
    margin: 3rem auto;
    text-align: center;
  }
}

Final step, let’s check out the new logo and icons.

Summary

There you have it! With around 10 lines of code you can brand the admin panel, update metadata and add custom components to effectively white label the admin panel for your clients or users.

Payload gives you the freedom and control to customize other aspects too, like the swapping out the Dashboard or creating custom inputs, to learn more about the admin panel and custom components—check out the pages below.

Read More

• Admin Panel
• Custom Components

Questions or Comments?

Join us on GitHub discussions.