Puck Extended

A component library that extends Puck — the open-source, headless visual page editor for React — with additional UI components, field overrides, media/page pickers, rich text extensions, and design system utilities.

What is Puck?

Puck is an open-source visual editor for React that lets developers build custom drag-and-drop page builders. You define your components and their editable fields; Puck provides the editing interface and renders the result. puck-extended is a companion package that augments Puck with ready-to-use components and helpers.

Installation

npm install @ckc-net/puck-extended

Features

Editor overrides plugin

Drop-in replacements for Puck's default editor UI: improved field labels with tooltips, grouped fields, and polished inputs (text, textarea, number with unit, select, radio, checkbox).

import { createPuckOverridesPlugin } from '@ckc-net/puck-extended'

const puckConfig = {
  components: { /* ... */ },
  plugins: [createPuckOverridesPlugin()],
}

MediaPicker

A full-featured media browser field: paginated library, search, drag-and-drop upload with progress, and support for images, videos and PDFs. Works in URL mode or ID-reference mode.

import { MediaPicker } from '@ckc-net/puck-extended'

// Inside a Puck field render
<MediaPicker
  value={value}
  onChange={onChange}
  mode="reference"
/>

Resolve a media reference to a URL at render time:

import { useMediaUrl } from '@ckc-net/puck-extended'

const url = useMediaUrl(value) // returns resolved URL string

PagePicker

Browse and search published pages, returning either a URL string or a page reference object. Useful for internal link fields.

import { PagePicker } from '@ckc-net/puck-extended'

<PagePicker value={value} onChange={onChange} />

import { usePageUrl } from '@ckc-net/puck-extended'

const url = usePageUrl(value)

ColorPicker

Color selection with a predefined palette (Tailwind-inspired swatches), a grayscale row, and a free hex input.

import { ColorPicker } from '@ckc-net/puck-extended'

<ColorPicker value={color} onChange={setColor} />

Rich text extensions

Extensions for Puck's rich text toolbar (requires Tiptap):

• RichTextMenuColorPicker — inline text color picker with preset colors and custom hex input
• RichTextMenuLink — link insertion popover backed by PagePicker

import { RichTextMenuColorPicker, RichTextMenuLink } from '@ckc-net/puck-extended'

Template block

Save and restore full page layouts. Supports localStorage (default) or a REST API backend for sharing templates across users.

import { createTemplateBlock } from '@ckc-net/puck-extended'

const TemplateBlock = createTemplateBlock({
  storageKey: 'my-project',
  // optional: use a REST API instead of localStorage
  apiUrl: () => '/api/templates',
  getHeaders: () => ({ 'X-CSRF-TOKEN': getCsrfToken() }),
})

Register TemplateBlock as a Puck component to let editors save and reload layouts.

UI components

A set of accessible Base UI wrapper components, all styled with Tailwind CSS:

| Component | Description | |-----------|-------------| | Accordion | Collapsible sections | | Badge | Status labels | | Button | Action button with variants | | Checkbox | Controlled checkbox | | Dialog | Modal dialog | | Input / InputGroup | Text input with optional addons | | Menu | Dropdown menu | | Pagination | Page navigation | | Popover | Floating popover | | Radio / RadioGroup | Radio selection | | ScrollArea | Custom scrollable container | | Select | Dropdown select | | Switch | Toggle switch | | Tabs | Tabbed panels | | Textarea | Multi-line input | | Toast | Notification toasts | | Tooltip | Hover tooltip |

Design utilities

Field-ready helpers for common CSS properties, ready to plug into any Puck component config:

import {
  animation,
  customClasses,
  display,
  fontWeight,
  lineHeight,
  margin,
  padding,
  position,
  size,
  spacing,
  textAlign,
  textColor,
  textDecoration,
  textSize,
  textTransform,
  typography,
} from '@ckc-net/puck-extended'

Each utility exports a Puck field definition (or a set of fields) that can be spread into a component's fields config.

Image optimization hook

Generate responsive srcSet and sizes attributes from a single image URL:

import { useOptimizedImage } from '@ckc-net/puck-extended'

const { src, srcSet, sizes } = useOptimizedImage(url, {
  breakpoints: [640, 1024, 1920],
})

Development

npm run dev        # Watch mode (JS + CSS)
npm run build      # Production build
npm run format     # Prettier

License

MIT — CKC-Net