Description: The x-cloak directive in AlpineJS is a crucial tool to hide Alpine-controlled elements until AlpineJS has fully initialized and styled them. This prevents a 'flash of unstyled content' (FOUC), where users might briefly see pre-render states of elements, such as content that should initially be hidden via x-show or x-if.
x-cloak attribute:
This is an AlpineJS directive that you add directly to HTML elements. For example:
<div x-show="isVisible" x-cloak>Sensitive Content</div>When Alpine.js initializes the component that manages this <div>, it will automatically remove the x-cloak attribute from the element. The element's visibility or content will then be controlled by Alpine's directives (like x-show in the example above).
CSS: [x-cloak] { display: none !important; }
This CSS rule is fundamental for x-cloak to function. You must include this rule in your project's stylesheets or within a <style> tag in your HTML's <head>. Here's how it looks:
[x-cloak] { display: none !important; }This rule targets any HTML element that currently possesses the x-cloak attribute and hides it using display: none. The !important flag is highly recommended to ensure this rule has high specificity and overrides other potentially conflicting display styles, thus reliably hiding the element until Alpine is ready.
Together, the x-cloak attribute and its corresponding CSS rule ensure a smooth user experience by preventing users from seeing elements in their raw, pre-Alpine state.
Forgetting to add the CSS rule for [x-cloak]:
The x-cloak attribute itself is merely a marker. Without the corresponding CSS rule [x-cloak] { display: none !important; }, the attribute does nothing to hide the element. AlpineJS's role is to remove the x-cloak attribute once it initializes the component; the CSS rule's role is to hide the element while the attribute is present. If you see FOUC, first check if this CSS rule is present and correctly applied in your project.
Applying x-cloak unnecessarily to static elements:
x-cloak is specifically designed for elements whose initial rendering state (e.g., visibility, content) is managed by AlpineJS (e.g., elements with x-show, x-if, x-text bound to dynamic data). Static HTML content that doesn't change based on Alpine's state doesn't need x-cloak. Adding it to static elements provides no benefit and might, in theory, slightly delay their display.
Overriding x-cloak CSS with less specific rules:
The !important in display: none !important; is generally recommended for x-cloak to ensure it takes precedence. If elements are still flashing despite having x-cloak and the CSS rule, use your browser's developer tools to inspect the element. Check if other CSS rules (perhaps more specific, or loaded later in the cascade) are overriding your [x-cloak] style. Ensure your [x-cloak] rule is effective.
This example demonstrates how x-cloak prevents a "flash of unstyled content".
The "Important Information" section below is initially hidden by CSS ([x-cloak] { display: none !important; }, which is included in the <head> of this document)
and will only appear once Alpine.js has initialized and determined its visibility based on the
showInfo state.
You are seeing this section because Alpine.js has initialized, removed the x-cloak attribute,
and the x-show="showInfo" directive evaluated to true.
Without x-cloak (and its CSS rule), this entire div might have briefly flashed on screen
when the page loaded, even though showInfo is initially false, before Alpine.js could process
x-show and hide it.
The important information is currently hidden. Click the button to reveal it.
On fast connections or simple pages, FOUC might be hard to perceive.
However, x-cloak is a crucial best practice for any Alpine-controlled content
that shouldn't be visible on initial page load, especially in more complex applications or on slower networks.
The key CSS rule [x-cloak] { display: none !important; } is vital and has been added
to the <head> of this document.