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.014 Creating Custom Templates (Front Page, Blog, 404, Single, Archive, Page)

Ep.013 Create Header & Footer Template Parts in WordPress Block Themes – Versana Theme Tutorial

Ep.012 Global Styles and theme.json in WordPress Block Themes – A Step-by-Step Guide with Versana Theme

Leave a ReplyCancel Reply