Skip to content

An admin bar for React apps using Payload

License

Notifications You must be signed in to change notification settings

payloadcms/payload-admin-bar

Repository files navigation

Payload Admin Bar

An admin bar for React apps using Payload as a headless CMS.

Installation

$ npm i payload-admin-bar
$ # or
$ yarn add payload-admin-bar

Basic Usage

import { PayloadAdminBar } from "payload-admin-bar";

export const App = () => {
  return (
    <PayloadAdminBar
      cmsURL="https://cms.website.com"
      collection="pages"
      id="12345"
    />
  );
};

Checks for authentication with Payload CMS by hitting the /me route. If authenticated, renders an admin bar with simple controls to do the following:

  • Navigate to the admin dashboard
  • Navigate to the currently logged-in user's account
  • Edit the current collection
  • Create a new collection of the same type
  • Logout
  • Indicate and exit preview mode

The admin bar ships with very little style and is fully customizable.

Dynamic props

With client-side routing, we need to update the admin bar with a new collection type and document id on each route change. This will depend on your app's specific setup, but here are a some common examples:

NextJS

For NextJS apps using dynamic-routes, use getStaticProps:

export const getStaticProps = async ({ params: { slug } }) => {
  const props = {};

  const pageReq = await fetch(`https://cms.website.com/api/pages?where[slug][equals]=${slug}&depth=1`);
  const pageData = await pageReq.json();

  if (pageReq.ok) {
    const { docs } = pageData;
    const [doc] = docs;

    props = {
      ...doc,
      collection: 'pages',
      collectionLabels: {
        singular: 'page',
        plural: 'pages',
      }
    };
  }

  return props;
}

Now your app can forward these props onto the admin bar. Something like this:

import { PayloadAdminBar } from 'payload-admin-bar';

export const App = (appProps) => {
  const {
    pageProps: {
      collection,
      collectionLabels,
      id
    }
  } = appProps;

  return (
    <PayloadAdminBar
      {...{
        cmsURL: 'https://cms.website.com',
        collection,
        collectionLabels,
        id
      }}
    />
  )
}

Props

Property Type Required Default Description
cmsURL string true http://localhost:8000 serverURL as defined in your Payload config
adminPath string false /admin routes as defined in your Payload config
apiPath string false /api routes as defined in your Payload config
collection string true undefined Slug of your collection
collectionLabels { singular?: string, plural?: string } false undefined Labels of your collection
id string true undefined id of the document
logo ReactElement false undefined Custom logo
classNames { logo?: string, user?: string, controls?: string, create?: string, logout?: string, edit?: string, preview?: string } false undefined Custom class names, one for each rendered element
logoProps {[key: string]?: unknown} false undefined Custom props
userProps {[key: string]?: unknown} false undefined Custom props
divProps {[key: string]?: unknown} false undefined Custom props
createProps {[key: string]?: unknown} false undefined Custom props
logoutProps {[key: string]?: unknown} false undefined Custom props
editProps {[key: string]?: unknown} false undefined Custom props
previewProps {[key: string]?: unknown} false undefined Custom props
style CSSProperties false undefined Custom inline style
unstyled boolean false undefined If true, renders no inline style
onAuthChange (user: PayloadMeUser) => void false undefined Fired on each auth change
devMode boolean false undefined If true, fakes authentication (useful when dealing with SameSite cookies)
preview boolean false undefined If true, renders an exit button with your onPreviewExit handler)
onPreviewExit function false undefined Callback for the preview button onClick event)