Component Design Guide

Learn how to design effective component schemas for your Storyblok content.

Overview

Well-designed components make content easier to:

• Create and edit
• Maintain consistency
• Reuse across projects
• Scale as needs grow

Component Design Principles

1. Single Responsibility

Each component should have one clear purpose.

Good:

• hero_section - Homepage hero only
• blog_post - Blog article content
• product_card - Product display

Bad:

• page_content - Everything for all pages
• flexible_block - 20 different layouts

2. Appropriate Nesting

Use nestable components for flexible layouts.

Create a "feature_section" component with:
- heading (text)
- intro (textarea)
- features (blocks - nestable "feature_card")

feature_card component:
- icon (asset)
- title (text)
- description (textarea)

3. Sensible Field Types

Choose the right field type for each need:

4. Validation and Constraints

Set appropriate limits:

For blog_post component:
- title: Required, max 100 characters
- slug: Required, regex pattern for URLs
- author: Required, from authors datasource
- publish_date: Required, datetime
- body: Required, richtext
- featured_image: Optional, asset (images only)
- tags: Optional, multi-option

Common Component Patterns

Content Page Components

page component (root):
- title (text, required)
- slug (text, required)
- meta_description (text, max 160)
- sections (blocks - nestable)

Available sections:
- hero_section
- text_section
- image_gallery
- cta_section
- faq_section

E-Commerce Components

product component:
- name (text, required)
- sku (text, required, unique)
- price (number, required)
- description (richtext)
- images (asset, multiple)
- category (single-option from datasource)
- variants (blocks - product_variant)
- related_products (multi-link)

Blog Components

blog_post component:
- title (text, required)
- slug (text, required)
- author (stories, single)
- publish_date (datetime)
- featured_image (asset)
- intro (textarea, max 300)
- body (richtext)
- categories (multi-option from datasource)
- tags (multi-option)
- related_posts (multi-link, blog_post)

Using Datasources

When to Use Datasources

Use datasources for:

• Options shared across components
• Lists that editors manage
• Options that change frequently
• Multi-language options

Use component options for:

• Fixed, technical choices
• Developer-managed options
• Rarely changing lists

Creating Datasources

Create a "blog_categories" datasource with entries:
- Technology
- Business
- Lifestyle
- News

Then use in blog_post component as single-option field

Component Organization

Component Groups

Create component groups to organize:
- "Page Sections" - hero, content, CTA sections
- "Content Types" - blog_post, product, landing_page
- "UI Components" - button, card, list
- "Marketing" - promo_banner, newsletter_signup

Naming Conventions

Good names:

• blog_post (noun, describes content)
• hero_section (descriptive, clear purpose)
• feature_card (specific, reusable)

Bad names:

• component_1 (meaningless)
• flexible (too vague)
• temp (unclear lifespan)

Testing Components

Before Rollout

For new "product_card" component:
1. Create test story
2. Fill all required fields
3. Test all field types work correctly
4. Preview in frontend
5. Test validation rules
6. Check mobile responsiveness

Iteration Process

After launching product_card v1:
1. Gather editor feedback
2. Identify pain points
3. Plan v2 improvements
4. Test changes on duplicate component
5. Migrate content safely

Best Practices

1. Start simple - Add fields as needed, don't over-engineer
2. Clear field names - Use descriptive, unambiguous names
3. Help text - Add descriptions for complex fields
4. Required sparingly - Only require truly mandatory fields
5. Group related fields - Use tabs for logical grouping
6. Test with content - Create real examples before rollout
7. Version carefully - Plan schema migrations
8. Document - Keep schema documentation up to date

Related Resources

• Safe Schema Changes
• Component Versioning
• Data Sources Tools

Need help designing components? Ask Claude to review your component schema or suggest improvements!