Naming Conventions

Consistent naming makes it easy to find blocks, avoid slug collisions, and keep your project predictable as the number of blocks grows. Every block in the library follows the same patterns.

Block Folder Structure

Each block lives in its own folder under a category:

1content/blocks/categories/[category]/[block-name]/
2├── config.ts
3├── component.tsx
4├── previews.tsx
5└── documentation.mdx

• Folder name: kebab-case (e.g., hero-1, feature-2). We use kebab-case because it maps cleanly to URL paths and file systems.
• Category name: plural, kebab-case (e.g., heros, features, faqs). Categories are plural because they contain multiple blocks of the same type.

File Naming

Every block folder contains the same four files. Using fixed file names means you always know exactly where to look — no guessing whether the config is called config.ts, block.ts, or Hero1.config.ts.

Code Naming

Code exports follow a predictable pattern so you can derive the export name from the block name without looking it up:

The config slug is what Payload uses internally as the blockType value when storing blocks. It is camelCase because Payload conventions use camelCase for slugs. The interfaceName is PascalCase because it becomes a TypeScript type.

Example

For a block called "Hero 1" in the "heros" category:

1content/blocks/categories/heros/hero-1/
2├── config.ts
3│   export const Hero1Config: Block = {
4│     slug: 'hero1Config',
5│     interfaceName: 'Hero1Type',
6│     ...
7│   }
8├── component.tsx
9│   export default function Hero1Component({ ... }: Hero1Type) { ... }
10├── previews.tsx
11└── documentation.mdx

Block Numbering

Numbered blocks within the same category (e.g., hero-1, hero-2) are distinct blocks with different layouts, not configuration variants of a single block. Hero 1 is a horizontal image hero, Hero 2 is a vertical centered hero — they have different components and different field sets.

We use numbers rather than descriptive names (like hero-horizontal) because names become subjective and unwieldy as the library grows. Numbers are short, unambiguous, and sort naturally.

Within a single block, visual variations (e.g., "with CTAs", "without image") are handled through the block's previews.tsx file and shown on the documentation page.

Third-Party Block Prefixes

Blocks ported from external libraries use a short source prefix to distinguish them from LayoutBlocks originals:

• ace-hero-1 — from Aceternity UI
• mui-cta-1 — from Magic UI

The prefix keeps the origin clear at a glance and prevents slug collisions with native blocks. See Third-Party Blocks for details.