Mutation Modifiers to create variations and different states of a block

mutation is a concept that allows for dynamic, block-specific modifications. Inspired by command-line flags, mutations offer a concise way to create block variants without the verbosity often associated with traditional modifier classes.

Definition and Purpose

Copy link to this section

A mutation in Blocktail is a block-level modifier that creates variants of your blocks.

A mutation represents a localized shift in reality, instantly transforming an element's state. It allows components to exist in multiple variations simultaneously, manifesting in a specific form when observed or interacted with.

Mutations are declared using double dashes, keeping your HTML clean and readable:

<article class="product_card --featured">
  <!-- Featured product card content -->
</article>

Mutation Capabilities

Copy link to this section

1. Block-Level Control

  • Mutations keep modifications where they belong - at the block level
  • Allows for specific changes to individual blocks without affecting others

2. Reduced Verbosity

  • We don't need to write long class names
  • Mutations are concise and clear and improve code readability

3. Easy Variants

  • Create multiple versions of a block without duplicating code
  • Enables variations without cluttering the base block structure

4. Clear Intent

  • Mutations clearly communicate the state or variant of a block
  • Improves code understandability for developers

5. Dynamic State Management

  • Can be pre-loaded on page load based on server-side calculations
  • Facilitates real-time changes through JavaScript

6. Observed Changes

Mutations can be observed and triggered through data observers.

Implementing Mutations

Copy link to this section

Pre-loaded Mutations

Copy link to this section

Apply mutations based on server-side logic:

<article class="product_card <?php echo $is_featured ? '--featured' : ''; ?>">
  <!-- Product card content -->
</article>

JavaScript-driven Mutations

Copy link to this section

Dynamically apply mutations:

document.querySelector('.product_card').classList.add('--featured');

Observed Mutations

Copy link to this section

Use data observers to monitor and trigger mutations:

<article class="product_card" data-observer="ProductCardObserver">
  <!-- Product card content -->
</article>

Combining Multiple Mutations

Copy link to this section

Combine mutations for complex states:

<article class="product_card --featured --sale">
  <!-- Featured product on sale content -->
</article>

Mutations vs. Contexts: Usage Comparison

Copy link to this section

While contexts provide broad, environmental changes, mutations offer granular, block-specific modifications:

  • Contexts: Applied to high-level elements, influencing multiple blocks
  • Mutations: Applied to individual blocks or tails for specific modifications
<main class="context[sales_event]">
  <article class="product_card --featured">
    <!-- Featured product card in a sales event context -->
  </article>
</main>

Read more about Mutations vs. Contexts

Mutation Implementation Best Practices

Copy link to this section
  • Clear Naming: Use descriptive, action-oriented names for mutations that clearly indicate their effect.
  • Single Responsibility: Each mutation should be responsible for a single aspect of modification.
  • Consistent Application: Apply mutations consistently across similar blocks for predictable behavior.

Mutation and UI Agent Interaction

Copy link to this section

While mutations offer block-level modifications, Blocktail also introduces the concept of ui-agents for more granular control. UI agents act as sanctioned micro-level mutation enforcers, ideally applied only at the tail level or a block without any further nested elements. They provide a controlled way to use utility classes, balancing flexibility with maintainability.

<article class="product_card --featured">
  <h2 class="-title ui--bold">Product Name</h2>
  <p class="-description ui--italic">Product description</p>
</article>

Whether pre-loaded, dynamically applied, or triggered through observers, mutations provide a powerful tool for creating adaptable, maintainable web components. By using mutations, you're taking direct control of your block variants while keeping your code clean and maintainable.

As you implement mutations in your projects, you'll discover their ability to enhance both the functionality and readability of your code, allowing for more intuitive and efficient web development.