Widget Blocks

Widget blocks provide common website functionality including search, archives, categories, RSS feeds, and other utility features.

Search

Name: core/search Description: Help visitors find your content.

Attributes

label (string) - Search label text
showLabel (boolean) - Display label
placeholder (string) - Placeholder text for input
buttonText (string) - Button text
buttonPosition (string) - Button position (button-inside, button-outside, no-button)
buttonUseIcon (boolean) - Use icon instead of text
isSearchFieldHidden (boolean) - Hide search field initially
query (object) - Search query parameters
width (number) - Search field width
widthUnit (string) - Width unit (px, %, etc.)

Supports

Align: left, center, right
Color: background, gradients, text
Spacing: margin
Typography: fontSize, lineHeight
Interactivity: true

Usage

// Basic search box
wp.blocks.createBlock('core/search', {
  label: 'Search',
  showLabel: false,
  placeholder: 'Search...',
  buttonText: 'Search',
});

// Search with icon button
wp.blocks.createBlock('core/search', {
  buttonPosition: 'button-inside',
  buttonUseIcon: true,
});

Categories (Terms List)

Name: core/categories Description: Display a list of all terms of a given taxonomy.

Attributes

taxonomy (string) - Taxonomy to display (category, post_tag, etc.)
displayAsDropdown (boolean) - Display as dropdown menu
showLabel (boolean) - Show dropdown label
label (string) - Custom label text
showPostCounts (boolean) - Show post counts
showHierarchy (boolean) - Show hierarchy
showEmpty (boolean) - Show empty categories
showOnlyTopLevel (boolean) - Show only top-level terms

Supports

Align: left, center, right
Color: background, text, link, gradients
Spacing: margin, padding
Typography: fontSize, lineHeight
Interactivity: clientNavigation

Usage

// Hierarchical category list
wp.blocks.createBlock('core/categories', {
  showHierarchy: true,
  showPostCounts: true,
  showEmpty: false,
});

// Custom taxonomy dropdown
wp.blocks.createBlock('core/categories', {
  taxonomy: 'product_category',
  displayAsDropdown: true,
  label: 'Product Categories',
});

Latest Posts

Name: core/latest-posts Description: Display a list of your most recent posts.

Attributes

postsToShow (number) - Number of posts to show, default: 5
displayPostContent (boolean) - Display post content
displayPostContentRadio (string) - Content type (excerpt, full_post)
excerptLength (number) - Excerpt length in words
displayPostDate (boolean) - Display post date
displayAuthor (boolean) - Display author
displayFeaturedImage (boolean) - Display featured image
featuredImageAlign (string) - Image alignment (left, right, center)
featuredImageSizeSlug (string) - Image size
featuredImageSizeWidth (number) - Image width
featuredImageSizeHeight (number) - Image height
addLinkToFeaturedImage (boolean) - Link featured image to post
postLayout (string) - Layout (list, grid)
columns (number) - Number of columns for grid
order (string) - Sort order (desc, asc)
orderBy (string) - Sort by (date, title, author)
categories (array) - Filter by category IDs
selectedAuthor (number) - Filter by author ID

Supports

Align: left, center, right, wide, full
Color: background, text, link, gradients
Spacing: margin, padding
Typography: fontSize, lineHeight
Interactivity: clientNavigation

Usage

// Simple post list
wp.blocks.createBlock('core/latest-posts', {
  postsToShow: 5,
  displayPostDate: true,
});

// Grid layout with excerpts
wp.blocks.createBlock('core/latest-posts', {
  postsToShow: 6,
  postLayout: 'grid',
  columns: 3,
  displayFeaturedImage: true,
  displayPostContent: true,
  excerptLength: 20,
});

Latest Comments

Name: core/latest-comments Description: Display a list of your most recent comments.

Attributes

commentsToShow (number) - Number of comments to show, default: 5
displayAvatar (boolean) - Display commenter avatar
displayDate (boolean) - Display comment date
displayContent (boolean) - Display comment content

Supports

Align: left, center, right, wide, full
Color: background, text, link, gradients
Spacing: margin, padding
Typography: fontSize, lineHeight
Interactivity: clientNavigation

Usage

wp.blocks.createBlock('core/latest-comments', {
  commentsToShow: 5,
  displayAvatar: true,
  displayDate: true,
  displayContent: false,
});

RSS

Name: core/rss Description: Display entries from any RSS or Atom feed.

Attributes

feedURL (string) - RSS feed URL
itemsToShow (number) - Number of items to show, default: 5
displayExcerpt (boolean) - Display excerpt
excerptLength (number) - Excerpt length in words
displayAuthor (boolean) - Display author
displayDate (boolean) - Display date
openInNewTab (boolean) - Open links in new tab
rel (string) - Link rel attribute
columns (number) - Number of columns
blockLayout (string) - Layout type (list, grid)

Supports

Align: left, center, right, wide, full
Color: background, text, link, gradients
Spacing: margin, padding

Usage

wp.blocks.createBlock('core/rss', {
  feedURL: 'https://example.com/feed',
  itemsToShow: 5,
  displayExcerpt: true,
  excerptLength: 50,
  displayDate: true,
});

Calendar

Name: core/calendar Description: A calendar of your site’s posts.

Attributes

month (number) - Display specific month
year (number) - Display specific year

Supports

Align: left, center, right
Color: background, text, link
Typography: fontSize, lineHeight
Interactivity: clientNavigation

Usage

// Current month calendar
wp.blocks.createBlock('core/calendar');

// Specific month
wp.blocks.createBlock('core/calendar', {
  month: 12,
  year: 2024,
});

Name: core/tag-cloud Description: A cloud of popular keywords, each sized by how often it appears.

Attributes

taxonomy (string) - Taxonomy to display (post_tag, category, etc.)
numberOfTags (number) - Maximum number of tags, default: 45
smallestFontSize (number) - Smallest font size
largestFontSize (number) - Largest font size
showTagCounts (boolean) - Show post counts

Supports

Align: left, center, right, wide, full
Spacing: margin, padding
Typography: lineHeight
Interactivity: clientNavigation

Usage

wp.blocks.createBlock('core/tag-cloud', {
  numberOfTags: 50,
  smallestFontSize: 12,
  largestFontSize: 24,
  showTagCounts: true,
});

Page List

Name: core/page-list Description: Display a list of all pages.

Attributes

parentPageID (number) - Parent page ID to list children
isNested (boolean) - Show nested pages

Supports

Color: background, text, link, gradients
Spacing: margin, padding
Typography: fontSize, lineHeight
Interactivity: clientNavigation
Allowed Blocks: core/page-list-item

Usage

// All pages
wp.blocks.createBlock('core/page-list', {
  isNested: true,
});

// Child pages of specific parent
wp.blocks.createBlock('core/page-list', {
  parentPageID: 10,
});

Custom HTML

Name: core/html Description: Add custom HTML code and preview it as you edit.

Attributes

content (string) - HTML content

Supports

Interactivity: clientNavigation
className: false
customClassName: false

Usage

wp.blocks.createBlock('core/html', {
  content: '<div class="custom-widget">Custom HTML content</div>',
});

Shortcode

Name: core/shortcode Description: Insert additional custom elements with a WordPress shortcode.

Attributes

text (string) - Shortcode text

Supports

className: false
customClassName: false

Usage

wp.blocks.createBlock('core/shortcode', {
  text: '[gallery id="123"]',
});

Name: core/social-links Description: Display icons linking to your social profiles or sites.

Attributes

iconColor (string) - Icon color slug
iconColorValue (string) - Custom icon color
iconBackgroundColor (string) - Icon background color slug
iconBackgroundColorValue (string) - Custom background color
customIconColor (string) - Custom icon color (deprecated)
customIconBackgroundColor (string) - Custom background color (deprecated)
openInNewTab (boolean) - Open links in new tab
showLabels (boolean) - Show text labels
size (string) - Icon size (default, large, huge)

Supports

Align: left, center, right
Color: background, gradients
Layout: default
Spacing: margin, padding, blockGap
Allowed Blocks: core/social-link

Usage

wp.blocks.createBlock('core/social-links', {
  openInNewTab: true,
  size: 'large',
}, [
  wp.blocks.createBlock('core/social-link', {
    service: 'twitter',
    url: 'https://twitter.com/username'
  }),
  wp.blocks.createBlock('core/social-link', {
    service: 'facebook',
    url: 'https://facebook.com/username'
  })
]);

Name: core/social-link Description: Display an icon linking to a social profile or site.

Attributes

service (string) - Social service name (twitter, facebook, instagram, etc.)
url (string) - Profile URL
label (string) - Custom label
rel (string) - Link rel attribute

Supports

Parent: core/social-links
Interactivity: clientNavigation
Reusable: false

Best Practices

Search optimization - Use descriptive button text and labels
Widget placement - Place widget blocks in sidebars and footer areas
Performance - Limit number of posts/comments shown in list widgets
RSS feeds - Validate feed URLs before adding RSS blocks
Social links - Keep social icons consistent in size and style
Accessibility - Ensure dropdown labels are descriptive
Custom HTML - Validate HTML code to avoid breaking layouts
Archive organization - Use hierarchical categories for better navigation

​Widget Blocks

​Search

​Attributes

​Supports

​Usage

​Archives

​Attributes

​Supports

​Usage

​Categories (Terms List)

​Attributes

​Supports

​Usage

​Latest Posts

​Attributes

​Supports

​Usage

​Latest Comments

​Attributes

​Supports

​Usage

​RSS

​Attributes

​Supports

​Usage

​Calendar

​Attributes

​Supports

​Usage

​Tag Cloud

​Attributes

​Supports

​Usage

​Page List

​Attributes

​Supports

​Usage

​Custom HTML

​Attributes

​Supports

​Usage

​Shortcode

​Attributes

​Supports

​Usage

​Social Icons

​Attributes

​Supports

​Usage

​Social Icon

​Attributes

​Supports

​Best Practices

Search

Attributes

Supports

Usage

Archives

Attributes

Supports

Usage

Categories (Terms List)

Attributes

Supports

Usage

Latest Posts

Attributes

Supports

Usage

Latest Comments

Attributes

Supports

Usage

RSS

Attributes

Supports

Usage

Calendar

Attributes

Supports

Usage

Tag Cloud

Attributes

Supports

Usage

Page List

Attributes

Supports

Usage

Custom HTML

Attributes

Supports

Usage

Shortcode

Attributes

Supports

Usage

Social Icons

Attributes

Supports

Usage

Social Icon

Attributes

Supports

Best Practices