Read the full API docs in the Wiki section
When building complex components for ASP.NET Razor Components there are often CSS classes generated by multiple factors. Styles can often be added by system & component state, public parameters, and static base CSS classes. Combining many CSS classes together doesn't scale well, and when components get large it can be tough to reason about. The CSS builder pattern fixes this problem by offering a easy to repeat, easy to read pattern to use across components in a project. A clean code approach to conditional CSS in Razor Components.
Given the component below, the Tab's CSS class is set by multiple sources.
The component has paramater UserCss which can be set at externally.
A base CSS class bl-nav-link which does not change.
Two state based CSS classes bl-active and bl-disabled which are dependent on if the Tab is active or disabled.
Rendering for the CSS class is spread across multiple concerns and is hard to maintain.
Component
<Tab UserCss="my-class" Disabled=true >...</Tab>Component Source Markup
<li class="bl-nav-item">
<a onclick=@Activate class="bl-nav-link @ActiveCssClass @DisabledCssClass" role="button">
@Title
</a>
</li>Component Source Logic
[Parameter] string UserCss = String.Empty;
protected string ActiveCssClass => IsActive ? "bl-active" : String.Empty;
protected string DisabledCssClass => Disabled ? "bl-disabled" : String.Empty;Using the CSS Builder pattern we can clean up the code and move everything to a single concern.
Refactoring the component, we move all of the CSS code to the components logic.
In the OnParameterSet lifecycle method, we condense all of the CSS responsibilities into a single variable ClassToRender (this name variable is optional).
Next, using the CssBuilder we define what classes should be added to the builder and when they should be rendered.
The pattern is as follows AddClass the CSS class and the condition when it should appear AddClass(value, when: bool).
If the value is static, we can discard the when parameter.
Finally, Build is called. All CSS classes are then combined into a single string, properly spaced and trimmed.
The refactored code becomes:
Component Source Markup (refactor)
<li class="bl-nav-item">
<a onclick=@Activate class="@ClassToRender" role="button">
@Title
</a>
</li>Component Source Logic (refactor)
protected override void OnParametersSet()
{
ClassToRender = new CssBuilder(UserCss)
.AddClass("bl-nav-link")
.AddClass("bl-active", when: IsActive)
.AddClass("bl-disabled", when: Disabled)
.Build();
}Component Source Logic (refactor with SetPrefix)
protected override void OnParametersSet()
{
ClassToRender = new CssBuilder(UserCss)
.SetPrefix("bl-")
.AddClass("nav-link")
.AddClass("active", when: IsActive)
.AddClass("disabled", when: Disabled)
.Build();
}If you encounter a dynamic value where some string is added to a CSS class name, we can easily handle this as well.
Consider the CSS namespace bl- must be prefixed to a value SomeValue supplied by the component state or user input.
This is easily handled with string interpolation ${var}.
protected override void OnParametersSet()
{
ClassToRender = new CssBuilder(UserCss)
.AddClass("bl-nav-link")
.AddClass("bl-active", when: IsActive)
.AddClass("bl-disabled", when: Disabled)
.AddClass("bl-${SomeValue}", when: IsConditionMet)
.Build();
}If you encounter dynamic values due to attribute splatting, we can easily handle this as well. Consider the senario where we need to merge a splatted CSS attribute while preserving default values.
<!-- API -->
<MyComponent class="custom-value">
<!-- Output -->
<div class="my-base custom-value"><div @attributes="AdditionalAttributes" class="@CssClass">
@code {
[Parameter(CaptureUnmatchedValues = true)]
public IReadOnlyDictionary<string, object> AdditionalAttributes { get; set; } = new Dictionary<string, Object>();
CssBuilder CssClass => new CssBuilder("my-base").AddClassFromAttributes(attributes);
}Func is also accepted as an arguement for the when parameter. This allows either inline functions or named functions to be called directly.
protected override void OnParametersSet()
{
ClassToRender = new CssBuilder(UserCss)
.AddClass("bl-nav-link")
.AddClass("bl-foo", when: ()=>
!string.IsNullOrEmpty(Foo) ||
!Disabled ||
IsActive)
.AddClass("bl-active", when: IsActive)
.AddClass("bl-disabled", when: Disabled)
.Build();
}Named function, example.
bool HasMeaningfulName() => !string.IsNullOrEmpty(Foo) || !Disabled || IsActive);
protected override void OnParametersSet()
{
ClassToRender = new CssBuilder(UserCss)
.AddClass("bl-nav-link")
.AddClass("bl-foo", when: HasMeaningfulName)
.AddClass("bl-active", when: IsActive)
.AddClass("bl-disabled", when: Disabled)
.Build();
}When using dynamic attributes may result in empty attribute. When Blazor renders an attribute that has an empty string value, it will result in an empty attribute tag. However, if the value is null the attribute will be excluded. When an empty attribute is expected, the extension method NullIfEmpty can be used to clean up the resulting markup. Note: This method is only necessary when no default value is supplied. Ex: new CssBuilder() or CssBuilder().Empty(). Forgetting to call NullIfEmpty should not have any impact on the UI.
<!-- Output with Empty String -->
<div class="">
<!-- Output with null -->
<div><div class="@CssClass">
@code {
//string CssClass => new CssBuilder().AddClassFromAttributes(attributes).Build();
string CssClass => new CssBuilder().AddClassFromAttributes(attributes).NullIfEmpty();
}