Custom fields

The plugin ships custom Puck fields for the things page components usually need: Payload media, colours, backgrounds, spacing and alignment. Each field has a factory (createMediaField()) that returns a Puck field definition, and a CSS helper that turns its value into styles. Everything here is imported from @delmaredigital/payload-puck/fields.

Field referenceCopy Anchor Link

The last three are for page-tree. The field components themselves (MediaField, ColorPickerField, BackgroundField and so on) are exported too, for use in your own custom fields.

createMediaField() takes label and apiEndpoint (default '/api/media'). createColorPickerField() takes showOpacity and presets; without presets it uses the theme's colour presets. createPaddingField() takes showUnits.

UsageCopy Anchor Link

import {
  createMediaField,
  createBackgroundField,
  backgroundValueToCSS,
} from '@delmaredigital/payload-puck/fields'

const HeroConfig = {
  fields: {
    image: createMediaField({ label: 'Background Image' }),
    background: createBackgroundField({ label: 'Overlay' }),
  },
  render: ({ image, background }) => (
    <section style={backgroundValueToCSS(background)}>
      {/* content */}
    </section>
  ),
}

CSS helpersCopy Anchor Link

The helpers turn field values into CSS strings, style objects or class names. Empty-value results depend on the helper: alignmentToFlexCSS() and alignmentToGridCSS() return an empty object ({}), so you can spread them into a style object.

import {
  backgroundValueToCSS,
  paddingValueToCSS,
  marginValueToCSS,
  borderValueToCSS,
  dimensionsValueToCSS,
  colorValueToCSS,
  animationValueToCSS,
  visibilityValueToCSS,
  transformValueToCSS,
  alignmentToFlexCSS,
  alignmentToGridCSS,
  sizeValueToCSS,
  getSizeClasses,
} from '@delmaredigital/payload-puck/fields'

const style = {
  ...backgroundValueToCSS(props.background),
  padding: paddingValueToCSS(props.padding),
  ...dimensionsValueToCSS(props.dimensions),
  ...alignmentToFlexCSS(props.contentAlignment),
  ...sizeValueToCSS(props.size),
}

For email components there are colorValueToEmailCSS, paddingValueToEmailCSS and backgroundValueToEmailCSS; see Email builder. The cn() class-name helper and the value types (ColorValue, PaddingValue, BackgroundValue and so on) are exported from the same entry point.

Content alignmentCopy Anchor Link

createContentAlignmentField() gives a visual 3×3 grid, like a d-pad, for positioning content:

import {
  createContentAlignmentField,
  alignmentToFlexCSS,
} from '@delmaredigital/payload-puck/fields'

const BannerConfig = {
  fields: {
    contentPosition: createContentAlignmentField({ label: 'Content Position' }),
  },
  render: ({ contentPosition }) => (
    <div style={{
      display: 'flex',
      minHeight: '400px',
      ...alignmentToFlexCSS(contentPosition),
    }}>
      <div>Positioned content</div>
    </div>
  ),
}

Pick the helper for the container you render:

• alignmentToFlexCSS(): for flexbox containers (justify-content and align-items).
• alignmentToGridCSS(): for grid containers (justify-content and align-content).
• alignmentToPlaceSelfCSS(): for individual grid items (place-self).
• alignmentToTailwind(): returns Tailwind classes (justify-* and items-*).

Field layoutCopy Anchor Link

createFieldLayout() arranges a component's sidebar fields into Puck 0.24 tabs and groups. It only changes the editor sidebar: props, saved data and rendering are untouched. Fields the layout doesn't mention are added to the first tab rather than hidden. Use the same tab labels across components and the open tab stays selected as editors move between them.

import { createFieldLayout } from '@delmaredigital/payload-puck/fields'

const HeroConfig = {
  fields: { /* _reset, heading, image, background, border, margin, ... */ },
  renderFields: createFieldLayout({
    pinned: ['_reset'], // shown above the tabs
    tabs: [
      { label: 'General', fields: ['heading', 'image'] },
      { label: 'Style', fields: [{ group: 'Box', fields: ['background', 'border'] }] },
      { label: 'Layout', fields: ['margin'] },
    ],
  }),
  render: /* ... */,
}