@flexiweb/right-panel

A PayloadCMS v3 plugin that replaces drawer overlays with a right panel interface for editing relationships, providing a more efficient side-by-side editing experience.

Quick Links: License • Documentation • Website

Table of Contents

• Introduction
• Features
• Getting Started
  • Installation
  • Basic Usage
• How It Works
• Configuration
  • Plugin Options
  • Excluding Collections
• Components
  • RightPanelEditView
  • RelationInRightPanelField
  • CustomContext Provider
• Customization
• License

Introduction

@flexiweb/right-panel is a powerful plugin for PayloadCMS v3 that enhances the relationship editing experience by replacing the default drawer overlay with a right panel interface. Instead of opening relationships in a modal drawer that covers the current view, this plugin opens related documents in a side panel, allowing you to view and edit both the parent document and its relationships simultaneously.

The plugin is designed to work seamlessly with the Flexiweb ecosystem and provides:

• Side-by-Side Editing: View and edit parent documents alongside their relationships
• Automatic Integration: Automatically applies to all collections and relationship fields
• Smooth UX: Seamless transitions with proper navigation state management
• Configurable: Exclude specific collections if needed
• Full Overridability: Customize every aspect of the plugin to fit your needs

Key Principles

• 🎯 Better UX: Side-by-side editing instead of overlay modals
• ⚡ Automatic: Works out of the box with all collections and relationship fields
• 🔧 Fully Configurable: Exclude collections or customize behavior
• 🛡️ Type Safe: Full TypeScript support with comprehensive type definitions
• ♿ Accessible: Maintains accessibility standards

Features

🎨 Right Panel Interface

• Opens related documents in a right-side panel (50% width)
• Main edit view automatically resizes to 50% when panel is open
• Smooth transitions and state management
• Preserves navigation context

🔗 Relationship Field Enhancement

• Adds an edit icon button next to all relationship fields
• Click to open related document in the right panel
• Works with all relationship field types
• Automatically applied to all collections

📱 Responsive Layout

• Dynamic width adjustment for main view and panel
• Proper overflow handling
• Maintains scroll behavior
• Hides navigation sidebar when panel is open

⚙️ Smart State Management

• Tracks panel open/close state
• Manages collection and document ID context
• Preserves step navigation history
• Automatic cleanup on unmount

Getting Started

Installation

Install the package using your preferred package manager:

# Using pnpm (recommended)
pnpm add @flexiweb/right-panel

# Using npm
npm install @flexiweb/right-panel

# Using yarn
yarn add @flexiweb/right-panel

Peer Dependencies

This plugin requires the following peer dependencies:

• [email protected]
• @payloadcms/[email protected]
• @faceless-ui/[email protected]

Basic Usage

1. Add the Plugin to Your Payload Config

import { flexiwebRightPanelPlugin } from '@flexiweb/right-panel'
import { buildConfig } from 'payload'

export default buildConfig({
  plugins: [
    flexiwebRightPanelPlugin({
      // Optional: Configure plugin options
      excludedCollections: [], // Collections to exclude from the plugin
    }),
  ],
  // ... rest of your config
})

2. Use Relationship Fields

Once the plugin is installed, all relationship fields in your collections will automatically:

1. Display an edit icon button next to the relationship field
2. Open related documents in a right panel when clicked
3. Allow side-by-side editing of parent and related documents

3. Edit Relationships

To edit a relationship:

1. Navigate to any document with relationship fields
2. Find the relationship field you want to edit
3. Click the edit icon (✏️) next to the relationship field
4. The related document opens in the right panel
5. Edit both documents side-by-side
6. Close the panel by clicking the edit icon again or the close button

How It Works

Architecture

The plugin works by:

1. Replacing Edit Views: All collection edit views are replaced with RightPanelEditView, which wraps the default edit view and adds the right panel wrapper
2. Enhancing Relationship Fields: All relationship fields get a custom field component (RelationInRightPanelField) that adds an edit button
3. Context Management: A custom context provider (CustomContextProvider) manages the panel state, collection, and document ID
4. Dynamic Layout: The main edit view and right panel dynamically adjust their widths based on panel state

Component Flow

User clicks edit icon on relationship field
    ↓
RelationInRightPanelField sets context (collection, id, isRightPanelOpen)
    ↓
RightPanelDocumentWrapper detects state change
    ↓
Main edit view resizes to 50% width
    ↓
Right panel opens with DocumentDrawerContent
    ↓
User can edit both documents side-by-side

State Management

The plugin uses React Context to manage:

• isRightPanelOpen: Whether the right panel is currently open
• collection: The collection slug of the document in the panel
• id: The document ID in the panel
• inRightPanel: Whether the current view is inside a right panel
• prevStepNav: Previous navigation state for restoration

Configuration

Plugin Options

The plugin accepts the following configuration options:

type RightPanelPluginConfig = {
  disabled?: boolean // Disable the plugin entirely
  excludedCollections?: CollectionSlug[] // Collections to exclude
}

Example Configuration

flexiwebRightPanelPlugin({
  excludedCollections: ['users', 'media'], // Exclude these collections
})

Excluding Collections

If you want to exclude certain collections from the right panel functionality:

import { flexiwebRightPanelPlugin } from '@flexiweb/right-panel'

export default buildConfig({
  plugins: [
    flexiwebRightPanelPlugin({
      excludedCollections: ['users', 'media', 'logs'],
    }),
  ],
  // ... rest of your config
})

Excluded collections will:

• Not have their edit views replaced
• Not have relationship fields enhanced with edit buttons
• Continue to use the default PayloadCMS drawer behavior

Components

RightPanelEditView

The main edit view component that wraps the default PayloadCMS edit view and adds the right panel wrapper.

Location: @flexiweb/right-panel/components/RightPanelEditView

Usage: Automatically applied to all collections (unless excluded)

Features:

• Wraps the default EditView component
• Conditionally renders RightPanelDocumentWrapper based on context
• Handles URL parameters for nested panel detection

RelationInRightPanelField

A custom field component for relationship fields that adds an edit button.

Location: @flexiweb/right-panel/components/RelationInRightPanelField

Usage: Automatically applied to all relationship fields

Features:

• Renders the default RelationshipField component
• Adds an edit icon button when a relationship value exists
• Opens the right panel on click
• Manages panel state through context

Props: Extends RelationshipFieldClientProps from PayloadCMS

CustomContext Provider

A React context provider that manages the right panel state.

Location: @flexiweb/right-panel/providers/CustomContext

Usage: Automatically added to the PayloadCMS admin providers

Context Values:

• isRightPanelOpen: Boolean state for panel visibility
• setIsRightPanelOpen: Function to toggle panel
• collection: Current collection slug in panel
• setCollection: Function to set collection
• id: Current document ID in panel
• setId: Function to set document ID
• inRightPanel: Boolean indicating if current view is in panel
• setInRightPanel: Function to set panel context
• prevStepNav: Previous navigation state
• setPrevStepNav: Function to save navigation state
• resetRightPanel: Function to reset all panel state

Hook: useCustomContext() - Access the context in your components

Customization

Overriding Components

You can override the default components by customizing your PayloadCMS config:

export default buildConfig({
  plugins: [flexiwebRightPanelPlugin()],
  collections: [
    {
      slug: 'posts',
      admin: {
        components: {
          views: {
            edit: {
              default: {
                Component: YourCustomEditView, // Override the edit view
              },
            },
          },
        },
      },
      fields: [
        {
          name: 'author',
          type: 'relationship',
          relationTo: 'users',
          admin: {
            components: {
              Field: YourCustomRelationshipField, // Override the field component
            },
          },
        },
      ],
    },
  ],
})

Custom Styling

The plugin includes default styles in custom.css. You can override these styles in your own CSS:

/* Override right panel width */
.rightpanel {
  width: 40% !important; /* Default is 50% */
}

/* Customize edit view width */
.edit-view {
  width: 60% !important; /* When panel is open */
}

/* Style the relationship field icon */
.relation-field-icon {
  color: #your-color;
  padding: 8px;
}

Accessing Context in Custom Components

If you need to access the right panel context in your custom components:

import { useCustomContext } from '@flexiweb/right-panel/providers/CustomContext'

const MyCustomComponent = () => {
  const {
    isRightPanelOpen,
    collection,
    id,
    setIsRightPanelOpen,
  } = useCustomContext()

  // Use the context values
  return (
    <div>
      {isRightPanelOpen && (
        <p>Editing {collection} with ID {id}</p>
      )}
    </div>
  )
}

License

This software is provided free of charge for use, modification, and distribution by any individual or legal entity ("Licensee") whose total annual gross revenue does not exceed USD 250,000.

If the Licensee's annual gross revenue exceeds USD 250,000, a paid commercial license is required. For commercial licensing, contact the maintainer at [email protected].

See LICENSE.md for full license details.

Built with ❤️ for the PayloadCMS community

Website • GitHub • Documentation