WordPress Core Blocks — Every Built-in Block Explained with Examples

In this tutorial, you'll learn every built-in WordPress Gutenberg block — from text and media blocks to design, widget, theme, and embed blocks — with practical examples showing when and why to use each one.

What You'll Learn

• All text blocks: Paragraph, Heading, List, Quote, Code, Classic, Preformatted, Verse, Pullquote
• All media blocks: Image, Gallery, Audio, Video, File, Media & Text, Cover
• All design blocks: Buttons, Columns, Group, Stack, Row, Spacer, Separator
• All widget blocks: Shortcode, Archives, Categories, Latest Posts, Tag Cloud, Search, Calendar
• All theme blocks: Site Logo, Site Title, Navigation, Post Content, Post Title, Post Date
• All embed blocks: YouTube, Twitter/X, Vimeo, Spotify, TikTok, Instagram, GitHub
• Exactly when to use each block type for different content scenarios

Why It Matters

Gutenberg ships with over 60 built-in blocks. Most users only use Paragraph and Image, missing blocks like Columns, Cover, and Buttons that create professional layouts without any coding. Knowing every block means you can build complex, visually rich pages using only the core editor — no page Builder plugin needed.

Real-World Use

A landing page needs a full-width hero section with a background image and overlaid text (Cover block), a three-column feature grid (Columns block), a customer testimonial (Quote or Pullquote), and a call-to-action row (Buttons block). All of this is built with core blocks, no custom PHP or HTML required.

Learning Path

flowchart LR
    A[Gutenberg Editor] --> B[Core Blocks]
    B --> C[Text Blocks]
    B --> D[Media Blocks]
    B --> E[Design Blocks]
    B --> F[Widget Blocks]
    B --> G[Theme Blocks]
    B --> H[Embed Blocks]
    C --> I[Block Patterns]
    D --> J[Writing Posts]

Text Blocks

Text blocks handle written content. These are the blocks you'll use most often.

Paragraph

The most fundamental block. Use it for body text, descriptions, and any prose content.

This is a Paragraph block. You type normally, and it wraps into paragraphs like a word processor.

Settings in sidebar: Font size, drop cap, text color, background color, letter spacing, line height.

Heading

Creates section headings (H2 through H6). H1 is reserved for the post title by most themes.

<!-- Heading block outputs as -->
<h2>Section Title</h2>
<h3>Subsection Title</h3>

When to use it: To structure content. Every section should start with a heading. Use H2 for main sections, H3 for subsections, H4 for sub-subsections.

List

Creates bulleted or numbered lists. Supports nested lists (lists within lists).

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

When to use it: For steps, features, ingredients, or any grouped items. Lists are easier to scan than paragraphs.

Quote

Displays a block quotation with a citation line underneath. The citation appears in italics by default.

> The best way to predict the future is to invent it.
> — Alan Kay

Code

Displays text in a monospace font inside a code-styled box. Ideal for short code snippets inline with content.

print("Hello, World!")

Important: The Code block does not apply syntax highlighting. For highlighted code, use a plugin like SyntaxHighlighter or the block patterns approach.

Classic

Embeds the old TinyMCE editor inside a single block. Useful for pasting content from Microsoft Word or Google Docs.

When to use it: When Gutenberg's block-by-block Parsing breaks complex formatting from other editors. The Classic block preserves the original HTML.

Preformatted

Displays text exactly as typed, preserving spaces and line breaks, in a monospace font. Unlike the Code block, it uses a slightly different visual style.

Column 1    Column 2    Column 3
Value A     Value B     Value C

Verse

Similar to Preformatted but styled specifically for poetry or song lyrics — centers the text and preserves line breaks.

Roses are red,
Violets are blue,
Gutenberg is awesome,
And so are you.

Pullquote

A visually prominent quote that "pulls out" from the main content. Usually styled with a larger font, different color, or quotation marks. Unlike the Quote block, Pullquote does not have a dedicated citation line.

When to use it: To highlight a key sentence or statistic from your article — draws the reader's eye to the most important takeaway.

Media Blocks

Media blocks handle images, videos, audio, and files.

Image

Inserts a single image from the media library or by URL.

<!-- Outputs as -->
<figure class="wp-block-image">
    <img src="photo.jpg" alt="Description" />
</figure>

Settings: Image size (thumbnail, medium, large, full), image dimensions, alt text, link destination, border radius, alignment.

Gallery

Displays multiple images in a grid layout.

Settings: Number of columns, image size, link to (attachment page, media file, none), random order, captions.

When to use it: Photo galleries, portfolio grids, product image sets.

Audio

Embeds an audio player with play/pause controls. Supports MP3, WAV, OGG, and M4A formats.

[audio mp3="podcast-episode-1.mp3"][/audio]

Video

Embeds a video player directly from the media library. Supports MP4, WebM, and OGV formats.

When to use it: Self-hosted video content. For YouTube or Vimeo, use the Embed block instead for better performance.

File

Creates a download link for any file type in the media library.

<a href="document.pdf">Download PDF (2.3 MB)</a>

When to use it: PDF guides, downloadable templates, ZIP archives.

Media & Text

Places an image or video side by side with text. The media can be on the left or right.

When to use it: "About" sections with photo + bio, product features with image + description.

Cover

A full-width background image or video with overlaid text and buttons. The overlay ensures text remains readable regardless of the background.

<div class="wp-block-cover" style="background-image: url(hero.jpg);">
    <span class="wp-block-cover__background" style="opacity: 0.5;"></span>
    <div class="wp-block-cover__inner-container">
        <h2>Welcome to Our Site</h2>
        <p>Learn more about what we do</p>
    </div>
</div>

Settings: Fixed background (parallax effect), overlay opacity, minimum height, focal point, content position.

When to use it: Hero sections, landing page headers, call-to-action banners.

Design Blocks

Design blocks control layout and visual structure.

Buttons

Creates one or more buttons side by side. Each button has its own text, link, color, and border radius.

[Sign Up]  [Learn More]  [Contact Us]

Settings per button: Background color, text color, border radius, width (auto or full), link target.

Columns

Divides content into multiple columns (2 to 6). Each column can contain any other blocks.

[Column 1]  [Column 2]  [Column 3]
Paragraph   Image       List

When to use it: Feature grids, pricing tables, team member cards, any side-by-side content.

Group

A container that holds other blocks together. You can apply background color, padding, and margins to the entire group at once.

When to use it: To section off related content, apply a background to a specific section, or control spacing between sections.

Stack

A vertical layout container for placing blocks one after another with consistent spacing.

When to use it: When you want blocks stacked vertically with uniform gap.

Row

A horizontal layout container for blocks side by side with consistent spacing.

When to use it: Social media icon rows, inline navigation items, horizontal button groups.

Spacer

Adds empty space between blocks. You control the exact height in pixels.

Why use it instead of pressing Enter multiple times? The Spacer block gives you precise, consistent spacing. Multiple empty paragraphs create unpredictable gaps that vary by theme.

Separator

A horizontal line (thematic break) between sections. Has three styles: default (thin line), wide line, and dots.

<hr class="wp-block-separator" />

Widget Blocks

Widget blocks are designed for sidebars but work anywhere in the editor.

Theme Blocks

Theme blocks are dynamic — they pull content from your site automatically. These are essential for Full Site Editing (FSE) but can also be used in regular posts.

Site Logo

Displays the site logo set in the Customizer. If no logo is set, it shows nothing.

Site Title

Shows the site title as a link to the homepage.

Navigation

Displays a navigation menu. You can create, edit, and assign menus directly in the block.

Post Content

The most important theme block in Full Site Editing — it outputs the main content of a post or page. Used inside template files.

<!-- wp:post-content /-->

Post Title

Displays the current post's title. Used in single post templates.

Post Date and Post Author

Show the publication date and author name of the current post. Used in post meta sections.

Embed Blocks

Embed blocks convert a URL into an embedded player or preview. WordPress supports over 40 embed providers.

How Embed Blocks Work

Simply paste a supported URL on its own line in the editor:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Gutenberg automatically detects the URL and converts it to an Embed block. You can also manually choose the provider from the Embeds section in the block inserter.

Why Use Embed Blocks Instead of Direct HTML?

Embed blocks handle responsive sizing, privacy, and performance automatically. They also display properly in the visual editor, unlike raw iframe HTML.

Common Mistakes

1. Using Image block for backgrounds: An Image block places an image inline with text. For a full-width background with overlaid text, use the Cover block instead.

2. Overusing Columns with too many columns: Three columns work great on desktop but can become unreadable on mobile. Stick to 2-4 columns maximum.

3. Nesting Groups too deeply: Each level of Group nesting makes the HTML more complex and harder to style. Keep nesting to 2-3 levels.

4. Not using the Spacer block: Multiple empty paragraphs create inconsistent spacing. Use the Spacer block for exact pixel-perfect gaps.

5. Ignoring the List View panel: Long posts with many blocks are hard to navigate by scrolling. Use the List View (top-left icon) to see all blocks at once and jump between them.

Practice Questions

1. Which block would you use to create a full-width hero section with a background image and overlaid text?
2. What's the difference between the Quote block and the Pullquote block?
3. How do you embed a YouTube video without copying the iframe HTML code?

Challenge: Recreate a simple landing page with a Cover block hero, a three-column feature section using Columns, a testimonial with Quote block, and a Buttons row with two call-to-action buttons. All using core blocks only — no page builders or custom code.

FAQ

Mini Project

Build a complete "About Us" page using core blocks only:

1. Cover block with a hero image, overlay, and "About Our Company" heading
2. Media & Text block with your photo on the left and a bio paragraph on the right
3. Columns block with three columns showing "Mission", "Vision", "Values" as Heading + Paragraph
4. A Quote block with a customer testimonial
5. Buttons block with "Our Services" and "Contact Us" buttons side by side
6. A Separator block between sections
7. Preview and verify the layout on desktop and mobile

What's Next

Now that you know every core block, learn Block Patterns and Reusable Blocks to save time by reusing entire layouts. Then dive into Categories and Tags to organize your content effectively.

Also explore Writing Posts and Managing Pages for the complete content workflow.