Content blocks with @content in SASS - Deep Dive

Overview - Content blocks with @content

What is it?

Content blocks with @content in Sass let you pass a chunk of CSS code into a mixin to be used inside it. This means you can write reusable styles that accept custom CSS from where you call them. It works like giving a box a special slot where you can put your own decorations. This helps keep your styles organized and flexible.

Why it matters

Without content blocks, mixins are limited to fixed styles and can’t adapt to different needs easily. Content blocks let you write one mixin that can do many things depending on the CSS you pass in. This saves time, reduces repeated code, and makes your styles easier to maintain and update.

Where it fits

Before learning content blocks, you should know basic Sass mixins and how to write nested CSS. After mastering content blocks, you can explore advanced Sass features like control directives (@if, @each) and functions for even more powerful style logic.

Mental Model

Core Idea

Content blocks with @content let you pass custom CSS into a mixin, making reusable styles flexible and adaptable.

Think of it like...

It’s like ordering a plain cake and bringing your own toppings to decorate it exactly how you want.

Mixin with @content usage:

+---------------------------+
| Mixin (plain cake)         |
| +-----------------------+ |
| | @content (your topping)| |
| +-----------------------+ |
+---------------------------+

When called:

+---------------------------+
| Call mixin                |
| +-----------------------+ |
| | Your CSS block         | |
| +-----------------------+ |
+---------------------------+

Build-Up - 6 Steps

1

Foundation

Understanding Sass Mixins Basics

Concept: Learn what a mixin is and how it helps reuse CSS code.

A mixin in Sass is like a reusable style recipe. You write it once and use it many times. For example: @mixin button-style { padding: 1rem; border-radius: 0.5rem; background-color: blue; color: white; } .button { @include button-style; } This applies the same styles to .button without repeating code.

Result

The .button class gets padding, rounded corners, blue background, and white text.

Understanding mixins is key because content blocks build on this idea by letting you add custom styles inside reusable blocks.

2

Foundation

Introducing @content in Mixins

Concept: Learn how @content lets you pass a block of CSS into a mixin.

You can add @content inside a mixin to create a placeholder for custom CSS: @mixin card { border: 1px solid gray; padding: 1rem; @content; } .card { @include card { background-color: lightyellow; } } Here, the background color is passed into the mixin’s @content slot.

Result

The .card class has a border, padding, and a light yellow background from the passed content.

Knowing @content lets you customize reusable styles without changing the mixin itself, making your CSS more flexible.

3

Intermediate

Using @content with Parameters

🤔Before reading on: Do you think @content can accept parameters like mixins? Commit to your answer.

Concept: Understand that @content itself does not take parameters, but mixins can have parameters alongside @content.

You can combine mixin parameters with @content to make flexible styles: @mixin button($color) { padding: 1rem; background-color: $color; @content; } .button-primary { @include button(blue) { color: white; } } .button-secondary { @include button(gray) { color: black; } } This way, the mixin controls the main style, and @content adds custom tweaks.

Result

.button-primary has blue background and white text; .button-secondary has gray background and black text.

Understanding that @content is a CSS block slot, not a function with parameters, helps avoid confusion and misuse.

4

Intermediate

Nesting @content for Complex Styles

🤔Before reading on: Can you nest @content inside other selectors within a mixin? Commit to your answer.

Concept: Learn that @content can be placed anywhere inside a mixin, including nested selectors, to inject custom CSS deeply.

Example: @mixin card { border: 1px solid gray; padding: 1rem; .header { font-weight: bold; } @content; } .card { @include card { .header { color: red; } .footer { font-size: 0.8rem; } } } This lets you customize nested parts inside the mixin.

Result

The .card class has border and padding; .card .header is bold and red; .card .footer has smaller font.

Knowing you can inject CSS deeply inside nested selectors with @content unlocks powerful style composition.

5

Advanced

Combining @content with Control Directives

🤔Before reading on: Do you think @content can be conditionally included inside a mixin? Commit to your answer.

Concept: Learn how to use @content with @if or @each to conditionally or repeatedly include custom CSS blocks.

Example: @mixin theme($dark: false) { background-color: if($dark, black, white); color: if($dark, white, black); @if $dark { @content; } } .box { @include theme(true) { border: 1px solid white; } } Here, @content runs only if $dark is true.

Result

The .box has black background, white text, and a white border because $dark is true.

Understanding that @content can be controlled by logic inside mixins lets you build smarter, adaptable styles.

6

Expert

How @content Affects CSS Output Order

🤔Before reading on: Does the position of @content inside a mixin affect where the passed CSS appears in the final stylesheet? Commit to your answer.

Concept: Learn that the location of @content inside a mixin controls where the passed CSS is inserted in the compiled CSS output.

Example: @mixin example { border: 1px solid black; @content; padding: 1rem; } .test { @include example { background: yellow; } } The compiled CSS is: .test { border: 1px solid black; background: yellow; padding: 1rem; } If you move @content below padding, background appears after padding.

Result

The order of CSS properties in the final stylesheet matches the order of @content in the mixin.

Knowing how @content placement affects CSS order helps prevent unexpected style overrides and bugs.

Under the Hood

When Sass compiles, it treats @content as a placeholder inside a mixin. The CSS block you pass when including the mixin replaces the @content directive exactly where it appears. This means the compiler merges the mixin’s fixed styles with your custom CSS seamlessly, preserving nesting and order.

Why designed this way?

Sass was designed to keep CSS DRY (Don’t Repeat Yourself) but also flexible. @content was added to let developers inject custom styles without rewriting mixins or creating many variants. This design balances reuse with customization, avoiding bloated CSS and complex overrides.

+---------------------------+
| Mixin with @content        |
| +-----------------------+ |
| | Fixed styles           | |
| | @content placeholder   | |
| | More fixed styles      | |
| +-----------------------+ |
+-------------|-------------+
              |
              v
+---------------------------+
| Include mixin with block   |
| +-----------------------+ |
| | Custom CSS block       | |
| +-----------------------+ |
+---------------------------+

Compiler merges custom CSS into @content spot.

Myth Busters - 4 Common Misconceptions

Quick: Does @content accept parameters like a function? Commit to yes or no.

Common Belief: Many think @content works like a function and can take parameters directly.

Reality: @content is a CSS block slot and cannot take parameters. Parameters belong to the mixin itself.

Why it matters: Trying to pass parameters to @content causes errors or confusion, blocking flexible style design.

Quick: Does the order of @content inside a mixin affect the final CSS? Commit to yes or no.

Common Belief: Some believe @content is always appended at the end of the mixin’s styles.

Reality: @content is inserted exactly where placed in the mixin, affecting CSS property order.

Why it matters: Misunderstanding this can cause unexpected style overrides or specificity issues in the final CSS.

Quick: Can you use @content outside of mixins? Commit to yes or no.

Common Belief: Some think @content can be used anywhere in Sass files.

Reality: @content only works inside mixins; using it elsewhere causes errors.

Why it matters: Misusing @content leads to compilation failures and wasted debugging time.

Quick: Does @content create a new CSS scope or selector? Commit to yes or no.

Common Belief: Some assume @content wraps the passed CSS in a new selector or scope automatically.

Reality: @content injects the CSS block as-is, respecting the mixin’s current selector context.

Why it matters: Expecting automatic scoping can cause selector conflicts or unexpected styling.

Expert Zone

1

When multiple @content blocks are used in nested mixins, the innermost @content replaces the closest placeholder, which can be tricky to track.

2

Using @content with control directives like @if or @each allows conditional or repeated injection of CSS blocks, enabling dynamic style generation.

3

The order of @content relative to other mixin styles affects CSS cascade and specificity, so careful placement is crucial for predictable output.

When NOT to use

Avoid using @content when you only need simple style reuse without customization; plain mixins or functions are simpler. For very complex style variations, consider using Sass maps or functions instead of heavy @content blocks to keep code readable.

Production Patterns

In production, @content is often used in UI component libraries to create base style wrappers that accept custom overrides. It’s also common in theming systems where core styles are fixed but small custom tweaks are injected per theme or component.

Connections

Higher-order functions (programming)

Both allow passing a block of code to be executed inside another function or block.

Understanding @content as a way to pass code blocks helps grasp higher-order functions, which are fundamental in many programming languages.

Template slots (web components)

Both provide a placeholder inside a reusable structure where custom content can be inserted.

Knowing how @content works clarifies how web component slots let you customize parts of a component’s template.

Modular design (architecture)

Both promote building reusable parts with customizable interfaces to adapt to different needs.

Seeing @content as a modular customization point connects to how architects design flexible buildings with interchangeable parts.

Common Pitfalls

#1 Trying to pass parameters directly to @content block.

Wrong approach:

@mixin example {
@content($color);
}

@include example {
color: red;
};

Correct approach:

@mixin example($color) {
color: $color;
@content;
}

@include example(red) {
font-weight: bold;
};

Root cause:

Confusing @content as a function that accepts arguments instead of a CSS block placeholder.

#2 Placing @content outside of a mixin.

Wrong approach:

@content {
color: blue;
}

Correct approach:

@mixin example {
@content;
}

@include example {
color: blue;
};

Root cause:

Misunderstanding that @content only works inside mixins, not standalone.

#3 Assuming @content CSS always appears at the end of the mixin styles.

Wrong approach:

@mixin example {
border: 1px solid black;
padding: 1rem;
@content;
}

@include example {
background: yellow;
};

Correct approach:

@mixin example {
border: 1px solid black;
@content;
padding: 1rem;
}

@include example {
background: yellow;
};

Root cause:

Not realizing the position of @content controls where the passed CSS is inserted.

Key Takeaways

Content blocks with @content let you pass custom CSS into mixins, making styles reusable and adaptable.

The @content block is a placeholder inside a mixin where you inject your own CSS code when including it.

@content does not accept parameters; mixins can have parameters alongside @content for flexible styling.

The position of @content inside a mixin controls where the passed CSS appears in the final stylesheet.

Using @content with control directives enables conditional and dynamic style injection for advanced use cases.