Ep.015 Understanding the 20 Most Common WordPress Blocks (With Attributes Explained)

When you’re building a WordPress block theme, you’ll constantly use blocks like paragraphs, headings, images, covers, and more. But as a beginner, one of the most confusing parts is the HTML comment syntax used in block templates — those lines that start with . In this guide, we’ll go through 20 of the most commonly used core WordPress blocks, and for each one, you’ll learn:

The structure of a block in HTML templates
What each attribute means (align, className, dimRatio, etc.)
When and why to use it
Best practices for real-world theme development

🧩 Understanding Block Syntax First

Let’s look at a simple example:

<!-- wp:paragraph {"align":"center","className":"intro-text"} -->
<p class="intro-text has-text-align-center">This is a paragraph block.</p>
<!-- /wp:paragraph -->

🔍 Breaking it down:

 → This tells WordPress to render a Paragraph Block.
{} → Inside curly braces are block attributes in JSON format.
"align":"center" → Controls the text alignment (center, left, right).
"className":"intro-text" → Adds a custom CSS class for styling.
<p> → This is the actual HTML output.
 → Marks the end of the block.

💡 Tip: Every block has two main parts — its definition comment () and its closing comment ().

1. 📝 Paragraph Block

<!-- wp:paragraph {"align":"center","className":"intro-text"} -->
<p class="intro-text has-text-align-center">This is a paragraph block.</p>
<!-- /wp:paragraph -->

🧠 Attributes Explained:

"align":"center" → Aligns text in the center. Possible values: "left", "center", "right".
"className":"intro-text" → A custom CSS class you can define in your stylesheet.

💡 Why use it:

Paragraph blocks form the body of your page or post. Use the align attribute to position text and className for consistent typography across your site.

2. 🏷️ Heading Block

<!-- wp:heading {"level":2,"className":"section-heading"} -->
<h2 class="section-heading">Section Title</h2>
<!-- /wp:heading -->

🧠 Attributes Explained:

"level":2 → Defines the heading level (1–6, corresponding to <h1>–<h6>).
"className":"section-heading" → Helps target this heading in CSS.

💡 Concept:

Heading levels define the content hierarchy. Search engines and screen readers use them to understand structure.

3. 🖼️ Image Block

<!-- wp:image {"id":123,"sizeSlug":"large","linkDestination":"none","className":"featured-image"} -->
<figure class="wp-block-image size-large featured-image">
  <img src="example.jpg" alt="Demo" />
</figure>
<!-- /wp:image -->

🧠 Attributes:

"id":123 → Image attachment ID (automatically assigned by WordPress).
"sizeSlug":"large" → Image size (thumbnail, medium, large, or full).
"linkDestination":"none" → Prevents linking the image to a page or media file.
"className":"featured-image" → Custom class for styling.

💡 Concept:

Each image inserted in the block editor carries these properties. You can reuse them for responsive design or to control layout.

4. 🌅 Cover Block

<!-- wp:cover {"url":"cover.jpg","dimRatio":50,"minHeight":400,"className":"hero-cover"} -->
<div class="wp-block-cover hero-cover" style="min-height:400px">
  <span class="wp-block-cover__background has-background-dim"></span>
  <img class="wp-block-cover__image-background" src="cover.jpg" alt="" />
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"textAlign":"center"} -->
    <h2 class="has-text-align-center">Welcome</h2>
    <!-- /wp:heading -->
  </div>
</div>
<!-- /wp:cover -->

🧠 Attributes:

"url":"cover.jpg" → Background image URL.
"dimRatio":50 → Controls overlay opacity (0–100).
"minHeight":400 → Sets minimum height in pixels.
"className":"hero-cover" → Used for section-specific CSS.

💡 Concept:

A cover block creates hero sections with background images or videos. The inner-container holds nested blocks like headings or buttons.

5. 🧱 Group Block

<!-- wp:group {"className":"content-wrapper"} -->
<div class="wp-block-group content-wrapper">
  <div class="wp-block-group__inner-container">
    <p>Inner content</p>
  </div>
</div>
<!-- /wp:group -->

🧠 Attributes:

"className":"content-wrapper" → Defines outer container styling.

💡 Concept:

Think of the Group block as a div wrapper — it helps you apply backgrounds, padding, or layout structure to multiple inner blocks.

6–7. 🧩 Columns and Column Blocks

<!-- wp:columns {"align":"wide","className":"three-columns"} -->
<div class="wp-block-columns alignwide three-columns">
  <!-- wp:column -->
  <div class="wp-block-column"><p>Column 1</p></div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column"><p>Column 2</p></div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->

🧠 Attributes:

"align":"wide" → Makes columns stretch wider than content width.
"className":"three-columns" → Custom class for layout styling.

💡 Concept:

Columns create responsive layouts. Use "wide" or "full" alignments for horizontal spacing control.

8. 🖼️ Media & Text Block

<!-- wp:media-text {"mediaPosition":"right","mediaType":"image","className":"media-section"} -->
<div class="wp-block-media-text has-media-on-the-right media-section">
  <figure class="wp-block-media-text__media"><img src="image.jpg" alt="" /></figure>
  <div class="wp-block-media-text__content">
    <h3>Heading</h3><p>Description text.</p>
  </div>
</div>
<!-- /wp:media-text -->

🧠 Attributes:

"mediaPosition":"right" → Moves the image to the right side.
"mediaType":"image" → Defines the type (image/video).
"className":"media-section" → For consistent section styling.

💡 Concept:

This block is perfect for marketing or feature sections combining visuals and text.

9. 💬 Quote Block

<!-- wp:quote {"className":"testimonial"} -->
<blockquote class="wp-block-quote testimonial">
  <p>This is a quote block.</p>
  <cite>Author</cite>
</blockquote>
<!-- /wp:quote -->

🧠 Attribute:

"className":"testimonial" → Adds a unique style for quote boxes or testimonials.

💡 Concept:

The Quote block enhances readability by isolating key statements or testimonials.

10. ✨ Pullquote Block

<!-- wp:pullquote {"className":"highlight-quote"} -->
<figure class="wp-block-pullquote highlight-quote">
  <blockquote>
    <p>A highlighted quote</p>
    <cite>Someone</cite>
  </blockquote>
</figure>
<!-- /wp:pullquote -->

💡 Concept:

A pullquote is a visual quote used to grab attention. It supports background and text colors, ideal for magazine-style layouts.

11. 🔢 List Block

<!-- wp:list {"ordered":true,"className":"numbered-list"} -->
<ol class="numbered-list"><li>First</li><li>Second</li></ol>
<!-- /wp:list -->

🧠 Attribute:

"ordered":true → Uses <ol> instead of <ul> (ordered list).
"className":"numbered-list" → Custom styling.

💡 Concept:

Lists improve readability for steps, features, or key points.

12. 🧭 Navigation Block

<!-- wp:navigation {"className":"main-menu"} /-->

🧠 Attributes:

"className":"main-menu" → CSS class for header styling.

💡 Concept:

Used inside your header.html template to display menus dynamically.

13–15. 🌐 Site Blocks

🖼️ Site Logo

<!-- wp:site-logo {"width":120,"className":"site-logo"} /-->

"width":120 → Logo width in pixels.

🏷️ Site Title

<!-- wp:site-title {"className":"site-title"} /-->

💬 Site Tagline

<!-- wp:site-tagline {"className":"site-tagline"} /-->

💡 These three work together in your site header for branding consistency.

16. 📰 Post Title

<!-- wp:post-title {"level":1,"className":"post-heading"} /-->

"level":1 → Ensures it uses <h1> tag on single post pages.

💡 Concept: Displays the title of the current post or page dynamically.

17. 📄 Post Content

<!-- wp:post-content {"className":"entry-content"} /-->

💡 Displays the main content written in the editor. Usually wrapped inside the <main> element.

18. ✍️ Post Excerpt

<!-- wp:post-excerpt {"moreText":"Read More","className":"post-excerpt"} /-->

"moreText":"Read More" → Custom text for the “Read More” link.

💡 Concept: Used in blog archives or query loops.

19. 🔘 Buttons Block

<!-- wp:buttons {"className":"cta-buttons"} -->
<div class="wp-block-buttons cta-buttons">
  <!-- wp:button {"className":"primary-btn"} -->
  <div class="wp-block-button primary-btn"><a class="wp-block-button__link">Click Me</a></div>
  <!-- /wp:button -->
</div>
<!-- /wp:buttons -->

🧠 Attributes:

"className":"cta-buttons" → Styles the button group.
"className":"primary-btn" → Styles the button itself.

💡 Concept: Used for call-to-action sections (CTAs).

20. ➖ Separator Block

<!-- wp:separator {"className":"section-divider"} -->
<hr class="wp-block-separator section-divider" />
<!-- /wp:separator -->

"className":"section-divider" → Adds a custom divider style.

💡 Concept: Use between sections for visual separation.

🧭 How to Read Any Block Syntax

You can understand any block by remembering this formula:

<!-- wp:block-name {"attribute":"value"} -->
HTML output here
<!-- /wp:block-name -->

Everything between the comments is the rendered content.
Attributes inside {} define the block’s behavior and styling.
You can edit them manually in your templates/ or patterns/ folder.

💡 Best Practices Summary

Purpose	Attribute	Why It’s Important
Layout	`align`, `minHeight`, `dimRatio`	Controls size, position, background
Design	`className`, `style`	Allows custom CSS styling
Content	`level`, `ordered`, `moreText`	Defines hierarchy or display options
Reusability	Consistent class naming	Keeps your theme maintainable

🎓 Conclusion

Once you understand these 20 core blocks and how attributes define their behavior, building templates becomes effortless. Each attribute tells WordPress how to display a block — alignment, spacing, background, color, or hierarchy.

Next up, we’ll explore Block Patterns — where you’ll combine these blocks to build reusable design sections for your Versana theme.

🧩 Understanding Block Syntax First

🔍 Breaking it down:

1. 📝 Paragraph Block

🧠 Attributes Explained:

💡 Why use it:

2. 🏷️ Heading Block

🧠 Attributes Explained:

💡 Concept:

3. 🖼️ Image Block

🧠 Attributes:

💡 Concept:

4. 🌅 Cover Block

🧠 Attributes:

💡 Concept:

5. 🧱 Group Block

🧠 Attributes:

💡 Concept:

6–7. 🧩 Columns and Column Blocks

🧠 Attributes:

💡 Concept:

8. 🖼️ Media & Text Block

🧠 Attributes:

💡 Concept:

9. 💬 Quote Block

🧠 Attribute:

💡 Concept:

10. ✨ Pullquote Block

💡 Concept:

11. 🔢 List Block

🧠 Attribute:

💡 Concept:

12. 🧭 Navigation Block

🧠 Attributes:

💡 Concept:

13–15. 🌐 Site Blocks

🖼️ Site Logo

🏷️ Site Title

💬 Site Tagline

16. 📰 Post Title

17. 📄 Post Content

18. ✍️ Post Excerpt

19. 🔘 Buttons Block

🧠 Attributes:

20. ➖ Separator Block

🧭 How to Read Any Block Syntax

💡 Best Practices Summary

🎓 Conclusion

🧾 References

Related Posts

Ep.017 Working with Dynamic Content in WordPress Block Themes

Ep.016 Create and Use Block Patterns in WordPress Block Themes

Ep.014 Creating Custom Templates (Front Page, Blog, 404, Single, Archive, Page)

Leave a ReplyCancel Reply