Forem: Dan Ribbens

Handling authentication in NextJS on Payload CMS

Dan Ribbens — Tue, 23 Aug 2022 15:03:59 +0000

Understanding and building authentication can be a burden at best, and a security risk at worst. Let's get through it together!

Payload gives the most complete and flexible way to manage user collections that support all the different authentication needs of your sites. It does so using secure HTTP-only cookies and includes support of boilerplate workflows for password recovery and lockout. You can even use Payload to manage multiple auth collections or build in robust role based access controls.

By the end of this article you will have a full understanding of how to implement authentication of users on your frontend NextJS website that can be managed from the admin UI of Payload CMS.

Overview

There are two code repositories created for this article that will be used as reference.

payloadcms/next-auth-frontend—the React app built in NextJS. It is a starter website that includes login and logout routes and forms for login, forgot password and reset password. It also demonstrates how the frontend will call the backend for the authenticated user.
payloadcms/next-auth-cms—the Payload CMS app setup to handle the database, storing user credentials, and the APIs for handling the REST or GraphQL requests that our auth example is built on.

You can follow the getting started sections of each repo provided. Setup should only take a few minutes for each. The seeding functions are called from the onInit function found in the payload.config.ts of our next-auth-cms app. By starting the server you should already have both an admin user and a customer, as defined by each role and also a home page.

User Auth

Since the user has already been created in the onInit function, we should be able to start both frontend and backend services, open the browser to the locally running site to see the landing page.

We haven't logged in yet and the UI reflects that.

If we were to look at the browser inspection tools showing network traffic and refresh the page, we'd see a call being made to backend that identifies the user state. The route is a GET request to /api/users/me on the backend which at this point simply returned user: null.

That call has been defined as a useEffect built into the Auth Provider component of auth-next-frontend under /components/Auth/index.ts. It is helpful to understand that the user in this auth context at any given time may be one of three states: undefined, before the query has finished, null as a guest, or the successful user object being returned.

useEffect(() => {
  const fetchMe = async () => {
    const result = await fetch(`${process.env.NEXT_PUBLIC_CMS_URL}/api/users/me`, {
      // Make sure to include cookies with fetch
      credentials: 'include',
    })
      .then((req) => req.json());
    setUser(result.user || null);
  };
  fetchMe();
}, []);

Getting the correct user back from the API request is possible because of the http cookie included in the fetch request which Payload APIs are automatically built and ready to handle for us.

Login

Now that we have enjoyed lurking as a guest, let's go over login.

From the screenshot we have a basic form that does the work of sending the entered credentials to the auth provider by
calling the login from useAuth.

The login form can be found in the /pages/login/index.ts of auth-next-frontend and handles basic error messages but
is otherwise left as simple as possible.

Account management and access control

Assuming we were successful in entering the user credentials we should be at the /account page. This form is used to send updates on the user collection of the logged in user. There isn't any API work to be done since Payload already takes care of that for us and can be done with GraphQL or REST as we've done here.

Now we are able to make further calls to the API endpoints from our authenticated frontend. The API will read the user in a stateless way and execute the access control for the user needed for that request.

Checking into the backend code now, the user collection in next-auth-cms has access defined so that Bob or an Admin
role are the only ones able to read or update the user.

Logout

The logout functionality is very similar to login except that we set the user in the frontend state to null on completion. The backend API will no longer accept requests from the authentication cookie that was originally returned from logging in.

Create Account

Now that we are no longer authenticated as bob. We can create a new account. Here is the code that handles submitting the create-account form.

const onSubmit = useCallback(async (data: FormData) => {
  const response = await fetch(`${process.env.NEXT_PUBLIC_CMS_URL}/api/users`, {
    method: 'POST',
    body: JSON.stringify(data),
    headers: {
      'Content-Type': 'application/json',
    },
  })

  if (response.ok) {
    // Automatically log the user in
    await login({
      email: data.email,
      password: data.password
    });

    // Set success message for user
    setSuccess(true);

    // Clear any existing errors
    setError('')
  } else {
    setError('There was a problem creating your account. Please try again later.');
  }
}, []);

At a high level, we are sending form data to the POST endpoint /api/users followed by a login with the same credentials.

This is possible because of our access control on users. You may have noticed that the access for create is set to return true.
That allows a guest user to create a new customer account. Had that not been set, Payload would use the default access control, which allows requests for any logged in user. That wouldn't work for anonymous users of course.

You might be asking, What is stopping a user from creating an account with the role of admin?

Within the roles field you can see an additional access included so that only an admin is able to assign this particular field.

Another way you could handle this is by creating a separate collection for admins or customers outside of roles which would further separate security concerns, that is up to you.

Password recovery

The frontend also has pages built for users to recover a lost password. These forms are built to call the API routes built-in to Payload for the workflow needed to enter the email address, receive the email with a secure link, and complete the reset password.

Payload makes these easily configurable along with account lockouts and other security features. You can read the Authentication documentation for details.

Security

By separating our backend and frontend we also need to have Cross Origin Resource Sharing (CORS) properly configured. Without this, we would be prevented from making frontend calls to the API from a different web address. Payload has a simple configuration for both CORS and you can see it is already configured in the payload.config.ts file in next-auth-cms using environment variables defined in .env. You don't need to configure CORS if your requests are made from the same domain.

Using http-only cookies is a principal detail in how modern REST architecture works. It is an essential tool for building secure and scalable applications. Hopefully this guide helped you understand and implement it for your next big idea.

Wrapping up

That's it! We have fully locked down our app and given access to only the right people.

The two template repos built for this blog post are meant to be starting points that anyone can build on or reference. To use them in production be sure to remove the onInit seeding functions.

Find us on twitter @payloadcms if you liked this article or join our growing Discord community.

Payload is now completely free and open source

Dan Ribbens — Tue, 24 May 2022 17:53:07 +0000

Today is an extremely exciting day for Payload. Starting immediately, we're moving to a completely open source and totally free MIT licensing model. From this point on, Payload is now completely free for projects of any shape or size.

Since launching our public beta a little over a year ago, Payload has been met with intensely positive reception. Developers all over the world have contributed to its codebase and we've been humbled by the amazing feedback we've received. From feature ideas to code commits, contributions to Payload's core have come from outside of the Payload team itself.

That's a beautiful thing, and it's the core of what makes the concept of open-source software so powerful. The community should shape the software, and when this paradigm is embraced, the software will become more effective than it ever could have if kept behind closed doors. But the level of engagement and community partnership that we've seen has far outshined our expectations—and it didn't feel right that we were charging money for software that people were so openly contributing to and helping shape.

Apart from code contributions, our community has also been active in providing feedback to the Payload team, which helps us shape our trajectory and helps us understand the impressions of developers as they discover Payload for the first time. Our community has consistently reinforced the fact that open-source software is much more trusted by developers and business users alike, and proprietary licenses are often hurdles that need to be overcome when adopting new technology for any company.

Our mission is to build the most powerful developer-first headless CMS available. It's a tool that has an uncompromising focus on the developer experience—and for that reason, we want to make sure that we value developers' feedback over all else.

Effective immediately, we will be making Payload free forever and fully open-source by adopting an MIT license.

We hope that this move will drive adoption further across the internet and allow developers all over the world to see the value in what Payload offers. Over the next few months, we'll be developing documentation describing the inner-workings of Payload itself as well as expanding on our code contribution experience to lower the barrier of entry and add transparency to how Payload has achieved its level of functionality.

Our future business model

The Payload team will continue to exist and will be expanding over the next few months. We will continue to be the primary source of development for new features and roadmap items. There's a lot to come yet—including some extremely exciting secured funding announcements and our 1.0 release.

Long-term, we've identified a business model that is two-fold:

1. Enterprise licenses

Since launching our public beta, we've been asked for enterprise-level features like SSO, support packages where enterprises will have guaranteed response times from Payload core developers, dedicated chat channels for rapid and efficient co-working, dedicated customer success managers, and more. We will continue to offer enterprise agreements to Payload users who require an added level of functionality and support, and we'll continue to build on our enterprise offering over time. If you're interested in hearing more about our enterprise offering, shoot us an email.

2. Cloud hosting

Another piece of feedback that the core Payload team has received is in regards to how difficult it is to handle hosting and dev ops on your own. Great strides have been made elsewhere on the web in regards to hosting platforms, but as soon as you need a database, permanent file storage, and deliberate infrastructure for Node apps, hosting becomes much trickier and you often find yourself cobbling together three or four vendors to host a CMS.

As a result, our team has committed to building a cloud deployment platform for Payload, which will be the easiest, most cost-effective, and efficient way to deploy Payload CMS for production. It'll deliver you a database that you continue to own, API endpoints, permanent file storage, backups, branch-based auto deploys, and more. Just connect to your version control, configure environment variables, and benefit from auto-deploys on scalable and managed infrastructure - just like how it should be. Just like NextJS ❤, you'll be able to host Payload wherever you want on your own completely free of charge, but if you would rather have us handle hosting for you, we're going to build a beautiful platform that will make sure your CMS is hosted in the most effective and efficient way possible.

We're actively gathering feedback in regards to features and functionality for our new cloud deployment platform, so if you'd like to help shape where we go, please take part in the discussions on GitHub. Also, keep an eye out for a blog post that'll talk more about our cloud hosting plans.

More to come

We have many more announcements to come in the next few months. It's an extremely exciting time for the Payload team and our energy stems directly from the intensely positive feedback we receive from our community every day. Keep an eye out for more and we look forward to continuing to build Payload into the most powerful CMS it can possibly be.

Payload has been accepted into Y Combinator S22

Dan Ribbens — Tue, 17 May 2022 13:05:53 +0000

Today, we are thrilled to announce that Payload has been accepted into the Y Combinator S22 batch and has secured its first $500K in investment, which will ensure that our team will be able to continue to build Payload into the most powerful developer-first headless CMS available.

Since we started building Payload in 2018, our mission has been crystal-clear: finally give developers a better choice when it comes to working with a CMS. We've poured our hearts and souls into the architecture of Payload for almost four years, trying to realize our goal. Now, Payload is live and being used around the world. We're so happy to see such positive reception from the developer community, and that positivity fuels us to commit ourselves more and more every day to making Payload as great as it can possibly be.

The team at Y Combinator sees the value in what we've built and understands the potential for Payload to be developers' first choice when they select a headless CMS. They've officially given us a vote of confidence that we have what it takes to complete our mission, accepted us into their S22 batch, and invested $500K in our vision.

With this funding, we're going to catapult Payload to the next level.

We've got a lineup of extremely exciting announcements coming over the next few weeks—so keep an eye out for a ton more from our team!

Payload CMS Version 0.15.0 brings publishing, versions, performance, more

Dan Ribbens — Thu, 17 Mar 2022 15:53:24 +0000

We've just published our biggest version release yet. It comes with over 20 new Payload features and countless quality of life improvements for Payload developers and admin panel users.

We've been busy over the past few months. In addition to fixing bugs and adding polish to Payload's APIs and admin panel, we've released a ton of new features—some small, some massive. 0.15.0 is now available on NPM. Payload is now nearing our 1.0 release, and we couldn't be more excited.

New Features

Versions

By far the biggest change that payload@0.15.0 brings is the introduction of Versions, Drafts, and Autosave. Payload now includes a way for you to keep a running history of document changes over time. You can easily go back and compare two versions, and restore changes back to a specific date.

It's extremely performant and opting in is super easy.

For more information, check out the docs.

Drafts

In addition to simply storing changes to your documents over time, Payload now includes a full set of draft functionality where your admins can keep drafts of documents before publishing them. This is super useful when you want to preview changes on your frontend(s) before you actually publish changes, or if you want to build a way to schedule publish dates in the future.

You can use Payload's existing Access Control to closely manage what users can publish, what users can only save drafts, who can read draft documents, and much more. Check out the docs for more.

Autosave

If you've opted into versions and drafts, you can now enable Autosave on your collections so that your editors never lose their work again.

It's a powerful but beautifully simple feature that saves progress as your admins work.

New ways to customize Admin React components

In 0.15.0, we've introduced a suite of new ways that you can easily customize the Admin UI with custom React components. We now support the following custom components:

Custom Admin routes

You can now easily inject your own routes and views directly into the Payload UI which allow you to build absolutely anything you can think of. Build custom functionality, reports, and utilities right into the Payload admin UI with ease. Check out the docs for more info.

Login

BeforeLogin - allows you to inject a custom component like a welcome message or instructions above the Login form
AfterLogin - same as above, but below the form

The Payload public demo, showing how a BeforeLogin component might be used

Dashboard

BeforeDashboard - inject a custom component into the Dashboard view so you can add custom logic and components directly into the Dashboard without having to replace the entire view
AfterDashboard - same as above, but below the Dashboard

Nav

BeforeNavLinks - Add your own links, functionality, and whatever you need before the Nav component without having to replace the entire Nav itself
AfterNavLinks - same as above, but below the Nav sidebar links

Rich Text Upload fields

Payload's Rich Text Upload functionality just got a lot more powerful by allowing users to add their own fields & data to embedded rich text uploads. For example, if you want to allow your admins to "link" an upload to a post, you can build fields directly into the Rich Text Upload to allow them to "edit" the Upload, and link it to another document or URL. You could also build in alignment controls and sizing controls, but it's totally open-ended and uses the same field schema that Payload's collections and globals do. It's simple but extremely powerful.

Rich Text Indentation & Nested Bulleted Lists

Now, Payload ships with a built-in way to indent copy and nest bulleted lists.

Performance Optimizations

0.15.0 also comes with a suite of performance optimizations to both the API and the React Admin UI.

GraphQL Relationship Population

We've reduced the behind-the-scenes database queries that are run by half while querying relationship fields within GraphQL.

Relationship Admin Field

The Relationship field is now significantly more performant when being used with 10+ relationships.

Much more

To view the full list of performance optimizations and changes, check out the Changelog.

Bug fixes

In addition to all the new features and performance improvements that 0.15.0 brings, we've also fixed a handful of bugs. Since our beta launch, Payload has been put to the test in production projects around the world and our community has been so helpful to us in identifying bugs and writing up detailed reports regarding how to reproduce undesired behavior.

We're proud of the speed and commitment to solving issues that the Payload team has displayed over the past few months and are confident that this is only the beginning.

For a full list of bug fixes that are shipped with 0.15.0, check the Changelog.

Breaking changes

Payload strives to keep breaking changes to an absolute minimum so that you can update Payload with ease. With all of these new features, we're happy to report that the only breaking change in this minor version release is related to GraphQL errors, which are now structured more according to how a developer might expect them to be returned.

Thanks to GitHub user chladog for the ideas and discussion around how to improve them. If you are handling GraphQL errors on your frontend(s) and would like to know how to migrate to this new version, check here. for more details. Otherwise, you can update to 0.15.0 without fear of any breaking changes!

More to come

It's a very exciting time for Payload, and we're getting closer and closer to 1.0. We're already the most feature-rich TypeScript CMS there is, but with every release Payload gets more stable and more powerful—and it's only the beginning.

Keep an eye out for more to come - and as always, we'd love to know what you think. Head over to join our GitHub Discussions if you have questions, thoughts, feedback, or feature requests!

Add Dynamic Descriptions to Customize the Payload CMS Admin UI

Dan Ribbens — Tue, 03 Aug 2021 02:22:19 +0000

If you are using Payload CMS, you can now add descriptions to the admin UI on Fields, Globals and Collections.

Descriptions are useful for giving contextual information to help content authors in the admin UI. They can be set with static text or made to give dynamic feedback to support a variety of use cases. You can configure descriptions on fields, collections and globals.

All the description properties support three types:

String
Function returning a string
React Component to be rendered

Let us explore some examples that represent real-world use cases.

Field Descriptions

On most field types the description will be displayed immediately after the input; Field types array, block, and group will show the description below the label. A collection configured with simple text field descriptions would look like the following:

{
  // ... collapsed
  fields: [
    {
      name: 'Order Details',
      type: 'group',
      admin: {
        description: 'Customer can view this information'
      },
      fields: [
        {
          name: 'customerName',
          type: 'text'
        },
        {
          name: 'shipDate',
          type: 'date',
          admin: {
            description: 'Date when package label was created',
            width: '50%',
            date: {
              pickerAppearance: 'dayOnly'
            }
          }
        },
        // ... collapsed
      ]
    }
  ]
}

Now anyone in the editing screen can understand exactly what is being represented.

Dynamic Field Descriptions

As useful as static text can be, the editing experience can be further enhanced using functions or full react components. The Payload docs has examples for both.

Using a function:

const labelField = {
  name: 'label',
  type: 'text',
  maxLength: 20,
  admin: {
    description: ({ value }) => (
      typeof value === 'string' ? `${20 - value.length} characters left` : ''
    )
  }
};

Or a react component:

const CharacterCount: React.FC = ({ value }) => (
  <div>
    Character count:
    {' '}
    { value?.length || 0 }
  </div>
);

const descriptionField = {
    name: 'description',
    type: 'textarea',
    admin: {
      description: CharacterCount,
    },
  };

Using these descriptions on your fields, the admin UI gives feedback as the user enters information.

Collection Descriptions

They do not support passing in a value, but otherwise work the same as field descriptions. By using the description on a collection, the editor can gain knowledge about how the data is used.

A special case for collections with uploads is that the description also gets displayed on the modals for new file and selecting from existing.

Global Descriptions

Descriptions can also be added to the edit screen on a Global beneath the label. Again, you can use this to explain extra details to the editor.

export default {
  slug: 'navigation',
  admin: {
    description: 'Manage the website navbar and mobile menus',
  },
  // ...collapsed
}

Building Further

Writing helpful descriptions for users can reduce the need for training or add that extra polish to impress a client. You can help users be more comfortable in a system by providing relevant explanations. Not only that, you might find your own descriptions useful when you come back in after being gone a long time.

Want to share an idea or ask the community? We love hearing from you in the Github discussions.

Build a custom field color picker React component for Payload CMS

Dan Ribbens — Fri, 02 Jul 2021 11:03:57 +0000

You can build completely custom field types in Payload by swapping in your own React components for any field in your app. In this tutorial, we'll be showing you how.

Building your own custom fields in Payload is as easy as writing a React component. Any field type can be extended further to make your own custom field, right down to how it works in the admin panel. In this way, you can avoid reinventing everything about a field and only work on adding your custom business logic exactly how you need.

To demonstrate this, we're going to create a simple color picker component for use right in the Payload CMS admin panel. By the end of this guide, we'll have created a modular, reusable custom field that can be dropped into any Payload CMS app with ease.

The component will:

Store its value in the database as a string—just like the built-in text field type
Use a custom validator function for the color format, to enforce consistency on the frontend and backend
Handle sending and receiving data to the Payload API by leveraging Payload's useFieldType hook
Store and retrieve user-specific preferences using Payload's Preferences feature
Render a custom Cell component, showing the selected color in the List view of the admin panel

All the code written for this guide can be seen in the Custom Field Guide repository.

Get Started

You can use your own Payload app or start a new one for this guide. If you haven't started a project yet, you can get started 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.

Write the base field config

The first step is to create a new file in your app for our new field's config. That will let us import it to different collections wherever it is needed. Because we want our field to store a string in the database, just like the built-in text field type does, we'll set our field's type equal to text. That will tell Payload how to handle storing the data. We'll also write a simple validation function to tell the backend and frontend what to allow to be saved.

import { Field } from 'payload/types';

export const validateHexColor = (value: string): boolean | string => {
  return value.match(/^#(?:[0-9a-fA-F]{3}){1,2}$/).length === 1 || `${value} is not a valid hex color`;
}

const colorField: Field = {
  name: 'color',
  type: 'text',
  validate: validateHexColor,
  required: true,
};

export default colorField;

Note that though code snippets are TypeScript, it can be done the same way in regular JavaScript by omitting the extra
type declarations.

Import the field in a collection

We'll import the field to an existing collection, so we can see it in use, before building it up a bit more.

/src/collections/ToDoLists.ts:

import { CollectionConfig } from 'payload/types';
import colorField from '../color-picker/config';

const Todo: CollectionConfig = {
  fields: [
    colorField,
  ]
}

This is a good time to mention that because we're just dealing with JavaScript, you could import this field and use it anywhere. You could also change individual properties specific to this collection by destructuring the object and add extra properties you wish to set. To do that, in place of the imported colorField instead do { ...colorField, required: false }, or any other properties as needed.

Build the Edit Component

So far, the default Text component is still rendering in the admin panel. Let's swap that out with a custom component, and modify the field's config to include it.

Custom field components are just basic React components, so let's scaffold that out and then build the extra features one-by-one. Create a new file for the Field component:

/src/color-picker/InputField.tsx:

import React from 'react'

// this is how we'll interface with Payload itself
import { useFieldType } from 'payload/components/forms';

// we'll re-use the built in Label component directly from Payload
import { Label } from 'payload/components/forms';

// we can use existing Payload types easily
import { Props } from 'payload/components/fields/Text';

// we'll import and reuse our existing validator function on the frontend, too
import { validateHexColor } from './config';

// Import the SCSS stylesheet
import './styles.scss';

// keep a list of default colors to choose from
const defaultColors = [
  '#333333',
  '#9A9A9A',
  '#F3F3F3',
  '#FF6F76',
  '#FDFFA4',
  '#B2FFD6',
  '#F3DDF3',
];

const baseClass = 'custom-color-picker';

const InputField: React.FC<Props> = (props) => {
  const {
    path,
    label,
    required
  } = props;

  const {
    value = '',
    setValue,
  } = useFieldType({
    path,
    validate: validateHexColor,
  });

  return (
    <div className={baseClass}>
      <Label
        htmlFor={path}
        label={label}
        required={required}
      />
      <ul className={`${baseClass}__colors`}>
        {defaultColors.map((color, i) => (
          <li key={i}>
            <button
              type="button"
              key={color}
              className={`chip ${color === value ? 'chip--selected' : ''} chip--clickable`}
              style={{ backgroundColor: color }}
              aria-label={color}
              onClick={() => setValue(color)}
            />
          </li>
          )
        )}
      </ul>
    </div>
  )
};

export default InputField;

You'll see above that Payload automatically provides our React component with the props that it needs. The most important prop is the path, which we pass on to the useFieldType hook. This hook allows us to set the field's value and have it work with the rest of the Payload form.

The component returns the markup for the component, complete with a Label and a list of clickable colors.

This won't be very functional until we add styling. Let's add a new line to import a new stylesheet: import './styles.scss';. Create that file and paste in the following SCSS:

/src/color-picker/styles.scss:

@import '~payload/scss';

.custom-color-picker {
  &__colors {
    display: flex;
    flex-wrap: wrap;
    list-style: none;
    padding: 0;
    margin: 0;
  }
}

.chip {
  border-radius: 50%;
  border: $style-stroke-width-m solid #fff;
  height: base(1.25);
  width: base(1.25);
  margin-right: base(.5);
  box-shadow: none;

  &--selected {
    box-shadow: 0 0 0 $style-stroke-width-m $color-dark-gray;
  }

  &--clickable {
    cursor: pointer;
  }
}

The simple styles above will give the color "chips" a clickable circle to set the value and show which is currently selected.

Tip:

You'll notice that the SCSS above imports Payload styles directly. By recycling Payload styles as much as possible, the UI elements we are adding will not stand out and look unfamiliar to our admin panel users.

Build the Cell

Another part of the custom component that we can add is a nice way to display the color right in a collection List. There, we can create the following:

/src/color-picker/Cell.tsx:


import React from 'react';
import { Props } from 'payload/components/views/Cell';
import './styles.scss';

const Cell: React.FC<Props> = (props) => {
  const { cellData } = props;

  if (!cellData) return null;

  return (
    <div
      className="chip"
      style={{ backgroundColor: cellData as string }}
    />
  )
}

export default Cell;

Note that we can reuse our styles here as we want the color "chip" to appear the same. We get the cellData from the Prop and that will be our saved hex values for the field.

Add the components to the Field

Now that we have a functional component to serve as our input, we can update color-picker/config.ts with a new admin property:

import { Field } from 'payload/types';
import InputField from './InputField';
import Cell from './Cell';

const colorField: Field = {
  // ...
  admin: {
    components: {
      Field: InputField,
      Cell,
    },
  },
};

Now is a good time to see it working! After you login and navigate to the url to create a new Todo item you will see the component and can use it to create a new Todo list.

Back in the List view, you should also be able to see the color that was chosen right in the table. If you don't see the color column, expand the column list to include it.

Allowing users to add their own colors

What we have is nice if we want to control available color options closely, but we know our users want to add their own too. Let's add to the UI a way to do that and while we're at it we should store the user's newly added colors in Payload's user preferences to re-use color options without re-entering them every time.

To make the interactions possible, we'll add more state variables and useEffect hooks. We also need to import and use the validation logic from the config, and set the value in a new Input which we can import styles directly from Payload to make it look right.

User Preferences

By adding Payload's usePreferences() hook, we can get and set user specific data relevant to the color picker all persisted in the database without needing to write new endpoints. You will see we call setPreference() and getPreference() to get and set the array of color options specific to the authenticated user.

Note that the preferenceKey should be something completely unique across your app to avoid overwriting other preference data.

Now, for the complete component code:

/src/color-picker/InputField.tsx:

import React, { useEffect, useState, useCallback, Fragment } from 'react'

// this is how we'll interface with Payload itself
import { useFieldType } from 'payload/components/forms';

// retrieve and store the last used colors of your users
import { usePreferences } from 'payload/components/preferences';

// re-use Payload's built-in button component
import { Button } from 'payload/components';

// we'll re-use the built in Label component directly from Payload
import { Label } from 'payload/components/forms';

// we can use existing Payload types easily
import { Props } from 'payload/components/fields/Text';

// we'll import and reuse our existing validator function on the frontend, too
import { validateHexColor } from './config';

// Import the SCSS stylesheet
import './styles.scss';

// keep a list of default colors to choose from
const defaultColors = [
  '#333333',
  '#9A9A9A',
  '#F3F3F3',
  '#FF6F76',
  '#FDFFA4',
  '#B2FFD6',
  '#F3DDF3',
];
const baseClass = 'custom-color-picker';

const preferenceKey = 'color-picker-colors';

const InputField: React.FC<Props> = (props) => {
  const {
    path,
    label,
    required
  } = props;

  const {
    value = '',
    setValue,
  } = useFieldType({
    path,
    validate: validateHexColor,
  });

  const { getPreference, setPreference } = usePreferences();
  const [colorOptions, setColorOptions] = useState(defaultColors);
  const [isAdding, setIsAdding] = useState(false);
  const [colorToAdd, setColorToAdd] = useState('');

  useEffect(() => {
    const mergeColorsFromPreferences = async () => {
      const colorPreferences = await getPreference<string[]>(preferenceKey);
      if (colorPreferences) {
        setColorOptions(colorPreferences);
      }
    };
    mergeColorsFromPreferences();
  }, [getPreference, setColorOptions]);

  const handleAddColor = useCallback(() => {
    setIsAdding(false);
    setValue(colorToAdd);

    // prevent adding duplicates
    if (colorOptions.indexOf(colorToAdd) > -1) return;

    let newOptions = colorOptions;
    newOptions.unshift(colorToAdd);

    // update state with new colors
    setColorOptions(newOptions);
    // store the user color preferences for future use
    setPreference(preferenceKey, newOptions);
  }, [colorOptions, setPreference, colorToAdd, setIsAdding, setValue]);

  return (
    <div className={baseClass}>
      <Label
        htmlFor={path}
        label={label}
        required={required}
      />
      {isAdding && (
        <div>
          <input
            className={`${baseClass}__input`}
            type="text"
            placeholder="#000000"
            onChange={(e) => setColorToAdd(e.target.value)}
            value={colorToAdd}
          />
          <Button
            className={`${baseClass}__btn`}
            buttonStyle="primary"
            iconPosition="left"
            iconStyle="with-border"
            size="small"
            onClick={handleAddColor}
            disabled={validateHexColor(colorToAdd) !== true}
          >
            Add
          </Button>
          <Button
            className={`${baseClass}__btn`}
            buttonStyle="secondary"
            iconPosition="left"
            iconStyle="with-border"
            size="small"
            onClick={() => setIsAdding(false)}
          >
            Cancel
          </Button>
        </div>
      )}
      {!isAdding && (
        <Fragment>
          <ul className={`${baseClass}__colors`}>
            {colorOptions.map((color, i) => (
              <li key={i}>
                <button
                  type="button"
                  key={color}
                  className={`chip ${color === value ? 'chip--selected' : ''} chip--clickable`}
                  style={{ backgroundColor: color }}
                  aria-label={color}
                  onClick={() => setValue(color)}
                />
              </li>
            )
            )}
          </ul>
          <Button
            className="add-color"
            icon="plus"
            buttonStyle="icon-label"
            iconPosition="left"
            iconStyle="with-border"
            onClick={() => {
              setIsAdding(true);
              setValue('');
            }}
          />
        </Fragment>
      )}
    </div>
  )
};
export default InputField;

We made a lot of changes—hopefully the code speaks for itself. Everything we did adds to the interactivity and usability of the field.

Styling the input to look like Payload UI

Lastly we want to finish off the styles of our input with a few new pieces.

Update your styles.scss with the following:

/src/color-picker/styles.scss:

@import '~payload/scss';

.add-color.btn {
  margin: 0;
  padding: 0;
  border: $style-stroke-width-m solid #fff;
}

.custom-color-picker {
  &__btn.btn {
    margin: base(.25);

    &:first-of-type {
      margin-left: unset;
    }
  }

  &__input {
    // Payload exports a mixin from the vars file for quickly applying formInput rules to the class for our input
    @include formInput
  }

  &__colors {
    display: flex;
    flex-wrap: wrap;
    list-style: none;
    padding: 0;
    margin: 0;
  }
}

.chip {
  border-radius: 50%;
  border: $style-stroke-width-m solid #fff;
  height: base(1.25);
  width: base(1.25);
  margin-right: base(.5);
  box-shadow: none;

  &--selected {
    box-shadow: 0 0 0 $style-stroke-width-m $color-dark-gray;
  }

  &--clickable {
    cursor: pointer;
  }
}

Closing Remarks

The custom color picker in this guide serves as an example of one way you could extend the UI to create a better authoring experience for users.

I hope you're inspired to create your own fantastic UI components using Payload CMS. Feel free to share what you build in the GitHub discussions.

New pricing plans make Payload CMS free for personal use

Dan Ribbens — Tue, 02 Mar 2021 22:33:23 +0000

We are announcing new product tiers—most exciting of which is that Payload CMS now offers a free Personal plan

The Payload team has taken every piece of feedback to heart since we launched. We're elated with the positive reception overall. One recurring topic has been making Payload more accessible to individual, developers; we want Payload to be an easy choice for portfolio sites and individual projects. With that, we're announcing the brand new, free-forever Personal tier.

Every solo founder is faced with a ton of decisions—most critical of all is how to best use capital. We made one decision easy. Our personal plan is a completely free option for users to have a fully featured, headless CMS, on an individual basis.

One major benefit of using Payload is the developer experience. We wanted to extend that all the way through, including the pricing model.

Pricing Philosophy

As a self-hosted CMS, Payload doesn't have any business in how many user roles, content types or API requests your app handles. We don't want to take away functionality from solo developers. So, we’re launching a new and totally free Personal plan for individual developers that places absolutely no restrictions on what Payload features you get. It’s perfect for portfolio sites, personal projects, or APIs that will only ever have one admin panel user.

Building on that, the Team tier gives access to the admin panel up to five users. For larger teams we have the Pro option that removes the user limits entirely. With Pro, you can add as many users to enjoy the authoring experience as you wish.

See our pricing page for all the details.

Join the discussion

Come join the Payload discussions on Github.

Take a moment to share with us