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 Files

When you copy a block into your project, you get two files:

These are the only files you need. Each block on the LayoutBlocks website also has a previews.tsx file (for the live previews on this site) and a documentation.mdx file (for the docs page) — you do not copy these.

Folder Structure

We recommend organizing blocks by category so they are easy to find as your collection grows:

1src/blocks/
2├── heros/
3│   ├── hero-1/
4│   │   ├── config.ts
5│   │   └── component.tsx
6│   └── hero-2/
7│       ├── config.ts
8│       └── component.tsx
9├── features/
10│   └── feature-1/
11│       ├── config.ts
12│       └── component.tsx

• Folder name: kebab-case (e.g., hero-1, feature-2). Kebab-case 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.

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":

1// config.ts
2export const Hero1Config: Block = {
3  slug: 'hero1Config',
4  interfaceName: 'Hero1Type',
5  // ...
6}
7
8// component.tsx
9export default function Hero1Component({ ... }: Hero1Type) { ... }

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 shown on the block's detail page through different preview configurations.

Third-Party Block Prefixes (Planned)

When third-party blocks are added to the library, they will use a short source prefix to distinguish them from native LayoutBlocks:

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

The prefix will keep the origin clear at a glance and prevent slug collisions. See Third-Party Blocks for more on this planned feature.