Skip to content

Custom Block Types

When to Use

Creating reusable, fieldable block types that content editors can manage without code changes.

Steps

  1. Create block type via UI
  2. Navigate to /admin/structure/block-content/types
  3. Click "Add block type"
  4. Enter label and description

  5. Save

  6. Add fields to the block type

  7. Click "Manage fields" for your block type
  8. Add fields (text, image, entity reference, etc.)

  9. Configure field settings and display

  10. Configure display modes

  11. "Manage display" tab
  12. Arrange field order, formatters

  13. Create additional view modes if needed

  14. Create block content instances

  15. Navigate to /block/add/{block_type_machine_name}
  16. Fill in fields
  17. Save

  18. Mark as "Reusable" if it should appear in block library

  19. Place block instances

  20. /admin/structure/block
  21. "Place block" → Find your content block
  22. Configure region, visibility, cache

Decision Points

At this step... If... Then...
Step 1 (create type) Need multiple similar types Use consistent naming convention
Step 2 (fields) Fields shared across types Consider field reuse or base fields
Step 3 (display) Block appears in multiple contexts Create multiple view modes
Step 4 (instances) Content specific to one page Consider inline block instead
Step 5 (placement) Same block on many pages Use visibility conditions instead of multiple placements

Pattern

Programmatically creating a block type:

use Drupal\block_content\Entity\BlockContentType;

$block_type = BlockContentType::create([
  'id' => 'call_to_action',
  'label' => 'Call to Action',
  'description' => 'Promotional block with title, text, and button',
]);
$block_type->save();

// Add fields programmatically (see Field API)

Programmatically creating a block content instance:

use Drupal\block_content\Entity\BlockContent;

$block = BlockContent::create([
  'type' => 'call_to_action',
  'info' => 'Homepage CTA',
  'reusable' => TRUE,
  'field_title' => 'Join Today!',
  'field_description' => 'Sign up for our newsletter',
]);
$block->save();

Reference: core/modules/block_content/src/Entity/BlockContentType.php, core/modules/block_content/src/Entity/BlockContent.php

Common Mistakes

  • Creating block types when block plugin is more appropriate → Use plugins for logic/dynamic content
  • Making non-reusable blocks via UI instead of inline blocks → Use Layout Builder inline blocks for one-off content
  • Not planning field reuse across block types → Leads to field proliferation and maintenance issues
  • Forgetting to set "Reusable" checkbox → Block won't appear in block library
  • Over-using block content for simple static content → Consider static blocks or page content instead

See Also