Block attributes and controls in Wordpress - Deep Dive

Overview - Block attributes and controls

What is it?

Block attributes are pieces of data that store the settings or content of a block in WordPress's block editor. Controls are the user interface elements that let you change these attributes, like sliders, text fields, or color pickers. Together, they let you customize blocks easily without writing code. This system helps make blocks flexible and interactive for users.

Why it matters

Without block attributes and controls, blocks would be static and hard to customize, making content creation slow and frustrating. They solve the problem of letting users change block content and appearance visually, without touching code. This makes building websites faster and more accessible for everyone, even people who don’t know programming.

Where it fits

Before learning block attributes and controls, you should understand basic WordPress block development and JavaScript fundamentals. After this, you can learn about advanced block customization, dynamic blocks, and how to save and load block data efficiently.

Mental Model

Core Idea

Block attributes hold the block’s data, and controls let users change that data through the editor interface.

Think of it like...

Think of a block like a customizable toy car. The attributes are the car’s parts like color, wheels, and size. The controls are the buttons and knobs you use to change those parts to make the car look and work how you want.

┌───────────────┐       ┌───────────────┐
│   Block UI    │──────▶│   Controls    │
│ (what you see)│       │(buttons, etc.)│
└───────────────┘       └───────────────┘
         │                      │
         ▼                      ▼
┌───────────────────────────────┐
│        Block Attributes        │
│ (data like text, colors, size)│
└───────────────────────────────┘

Build-Up - 8 Steps

1

Foundation

What Are Block Attributes

Concept: Block attributes store the data that defines a block’s content and settings.

In WordPress blocks, attributes are like variables that hold information such as text, colors, or numbers. For example, a paragraph block’s attribute might hold the text you type. Attributes are defined in the block’s code and saved with the block.

Result

You understand that attributes are the data backbone of a block, holding everything that makes the block unique.

Understanding attributes as data containers helps you see how blocks remember user input and settings.

2

Foundation

What Are Block Controls

Concept: Controls are the interactive elements that let users change block attributes visually.

Controls appear in the block editor sidebar or toolbar. They can be text inputs, sliders, color pickers, or dropdowns. When a user changes a control, it updates the corresponding attribute behind the scenes.

Result

You see how controls provide a friendly way for users to customize blocks without code.

Knowing controls connect the user interface to attributes clarifies how blocks become interactive.

3

Intermediate

Defining Attributes in Block Code

🤔Before reading on: do you think attributes are defined inside the block’s edit function or separately? Commit to your answer.

Concept: Attributes are declared in the block’s registration code with types and sources.

When registering a block with registerBlockType, you define attributes as an object. Each attribute has a type (like string or number) and a source (where to get the data, e.g., from HTML or meta). This tells WordPress how to save and load the data.

Result

You can write block code that properly stores and retrieves user data.

Knowing how to define attributes correctly prevents data loss and ensures your block works reliably.

4

Intermediate

Connecting Controls to Attributes

🤔Before reading on: do you think controls update attributes directly or through a separate state? Commit to your answer.

Concept: Controls update attributes by calling a function that changes the attribute’s value.

In the block’s edit function, you use props.attributes to read values and props.setAttributes to update them. Controls like TextControl or ColorPicker call setAttributes with new values when users interact with them.

Result

Your block’s UI responds instantly to user input, updating the saved data.

Understanding this connection is key to making blocks that feel responsive and intuitive.

5

Intermediate

Using Inspector Controls for Sidebar Settings

Concept: Inspector Controls let you add controls to the block’s sidebar panel for extra settings.

WordPress provides the InspectorControls component to group controls in the sidebar. This keeps the main block area clean and puts advanced options in a dedicated place. You wrap controls inside in your edit function.

Result

Your block has a neat sidebar panel with controls that users can open or close.

Knowing how to organize controls improves user experience and block usability.

6

Advanced

Attribute Sources and Serialization

🤔Before reading on: do you think attribute data is always stored in block HTML or can it be saved elsewhere? Commit to your answer.

Concept: Attributes can get their data from different sources like HTML, block comment metadata, or post meta fields.

Attributes have a source property that tells WordPress where to find or save the data. For example, source: 'html' extracts data from the block’s HTML content, while source: 'attribute' reads from an HTML attribute. This affects how the block saves and loads data.

Result

You can create blocks that save data in the best place for your needs, improving compatibility and performance.

Understanding attribute sources helps you design blocks that work well with WordPress’s saving system.

7

Advanced

Custom Controls for Complex Interactions

🤔Before reading on: do you think you can create your own controls beyond the built-in ones? Commit to your answer.

Concept: You can build custom controls to handle unique user interactions not covered by default controls.

By creating React components and using setAttributes, you can make controls like drag-and-drop, multi-select, or complex color palettes. This lets you tailor the block editor experience exactly to your block’s needs.

Result

Your blocks can offer rich, user-friendly customization beyond simple inputs.

Knowing how to build custom controls unlocks advanced block design possibilities.

8

Expert

Performance and State Management in Controls

🤔Before reading on: do you think updating attributes immediately on every control change is always best? Commit to your answer.

Concept: Efficiently managing attribute updates and control state improves block editor performance and user experience.

Sometimes, updating attributes on every keystroke or change causes lag. Experts debounce updates or manage temporary local state inside controls before committing changes. This reduces unnecessary renders and improves responsiveness.

Result

Your blocks feel smooth and fast, even with complex controls.

Understanding performance tradeoffs in attribute updates helps you build professional-grade blocks.

Under the Hood

When a block is edited, the editor reads the block’s attributes from saved content or metadata. Controls in the editor UI call setAttributes to update these attributes, which triggers React to re-render the block with new data. When saving, WordPress serializes attributes back into HTML or metadata based on their source definitions. This cycle keeps the block’s data and UI in sync.

Why designed this way?

This design separates data (attributes) from UI (controls) to keep blocks flexible and maintainable. It leverages React’s reactive rendering for instant updates and uses WordPress’s serialization system to store data cleanly. Alternatives like storing all data in HTML without attributes would be fragile and hard to extend.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│  Saved Block  │◀──────│  Attributes   │◀──────│   Controls    │
│  Content/Data │       │ (data storage)│       │ (UI inputs)   │
└───────────────┘       └───────────────┘       └───────────────┘
         ▲                      │                      │
         │                      ▼                      ▼
    ┌─────────────┐         ┌───────────────┐      ┌───────────────┐
    │ Serialization│──────▶│ React Rendering│◀────│ User Actions  │
    └─────────────┘         └───────────────┘      └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think block attributes always store visible content only? Commit yes or no.

Common Belief: Attributes only hold the visible text or images inside a block.

Reality: Attributes can store any data needed for the block, including settings like colors, alignment, or even hidden metadata.

Why it matters: Assuming attributes only hold visible content limits your block’s flexibility and can cause you to miss important customization options.

Quick: Do you think controls automatically save data without calling setAttributes? Commit yes or no.

Common Belief: Controls automatically save changes without extra code.

Reality: Controls must call setAttributes explicitly to update block data; otherwise, changes won’t be saved.

Why it matters: Not calling setAttributes leads to blocks that appear editable but don’t save changes, confusing users.

Quick: Do you think all attribute data is saved inside the block’s HTML? Commit yes or no.

Common Belief: All attribute data is saved inside the block’s HTML content.

Reality: Some attributes are saved in block comments or post meta, not just HTML, depending on the source property.

Why it matters: Misunderstanding this can cause data loss or broken blocks when saving or migrating content.

Quick: Do you think updating attributes on every keystroke is always best? Commit yes or no.

Common Belief: Updating attributes immediately on every user input is always good.

Reality: Immediate updates can cause performance issues; sometimes debouncing or local state is better.

Why it matters: Ignoring this can make the editor laggy and frustrating for users.

Expert Zone

1

Attributes can have default values that initialize the block’s state before user input.

2

Using the source property wisely can optimize block saving and improve compatibility with other plugins.

3

Custom controls can manage their own internal state to reduce unnecessary attribute updates and improve performance.

When NOT to use

Avoid using complex controls or many attributes for very simple blocks; instead, use static blocks or reusable blocks. For dynamic data, consider server-side rendered blocks instead of heavy client-side controls.

Production Patterns

In production, blocks often use InspectorControls for advanced settings, debounce attribute updates for performance, and separate visual controls from data logic. Teams also create shared control components for consistency across blocks.

Connections

React State Management

Block attributes and controls use React’s state and props pattern to manage data and UI updates.

Understanding React’s state model helps grasp how attribute changes trigger UI re-renders in blocks.

User Interface Design

Controls are UI elements designed to make data editing intuitive and accessible.

Knowing UI design principles improves how you build controls that users find easy and pleasant to use.

Database Normalization

Separating block data (attributes) from presentation (HTML) is similar to separating data from display in databases.

This separation prevents data duplication and inconsistency, a principle shared across software design.

Common Pitfalls

#1 Not calling setAttributes inside control event handlers.

Wrong approach:

onChange={(value) => { /* no setAttributes call */ }}

Correct approach:

onChange={(value) => setAttributes({ attributeName: value })}

Root cause:

Misunderstanding that controls must explicitly update attributes to save changes.

#2 Defining attributes without specifying type or source.

Wrong approach:

attributes: { content: {} }

Correct approach:

attributes: { content: { type: 'string', source: 'html', selector: 'p' } }

Root cause:

Not providing enough information for WordPress to save and load attribute data correctly.

#3 Updating attributes on every keystroke causing lag.

Wrong approach:

onChange={(value) => setAttributes({ text: value })} // updates on every key

Correct approach:

Use local state and debounce before calling setAttributes to reduce updates.

Root cause:

Not managing performance by controlling how often attributes update.

Key Takeaways

Block attributes store all the data that makes a block unique and customizable.

Controls are the user-friendly interface elements that let users change those attributes visually.

Attributes must be properly defined with types and sources to save and load data reliably.

Controls update attributes by calling setAttributes, connecting user actions to data changes.

Managing attribute updates carefully improves editor performance and user experience.