Description: The x-cloak directive in AlpineJS helps you 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 the pre-render, raw HTML state of elements before AlpineJS takes control to show, hide, or modify them.
x-cloak attribute:
This is an AlpineJS directive that you add directly to an HTML element. For example: <div x-cloak>...</div>.
By itself, x-cloak doesn't do anything functional. It acts as a marker. AlpineJS is designed to automatically remove the x-cloak attribute from an element (and its children) once that part of the DOM has been initialized and processed by Alpine.
CSS: [x-cloak] { display: none !important; }
This is the crucial CSS rule that works in tandem with the x-cloak attribute. You must include this rule in your global stylesheet or within a <style> tag in your HTML's <head>.
[x-cloak] { display: none !important; }How it works:
[x-cloak] targets any HTML element that currently has the x-cloak attribute.display: none !important; hides these elements. The !important flag is generally recommended to ensure this rule has high specificity and overrides other display styles that might otherwise make the element visible prematurely.x-cloak attribute from an element, this CSS rule no longer applies to that element. The element then becomes visible according to its normal styling or as dictated by other Alpine directives like x-show or x-if.Forgetting to add the CSS rule for [x-cloak]:
The most common mistake is adding the x-cloak attribute to elements but forgetting to include the corresponding CSS rule: [x-cloak] { display: none !important; }. Without this CSS, the x-cloak attribute has no effect, and FOUC can still occur. AlpineJS only removes the attribute; the hiding is purely a CSS mechanism triggered by the attribute's presence.
Applying x-cloak unnecessarily to static elements:
x-cloak is intended for elements whose initial display state or content is managed or significantly altered by AlpineJS. If an element is purely static (i.e., its content and visibility don't depend on Alpine logic), adding x-cloak is unnecessary. While the performance impact is usually negligible, Alpine still has to process and remove the attribute, which could theoretically introduce a minuscule delay in rendering that static content for no benefit.
Overriding x-cloak CSS with less specific rules (or more specific conflicting rules):
The !important in display: none !important; is very helpful in ensuring the x-cloak rule takes precedence. However, if you have other CSS rules that are more specific and also use !important to set a display property (e.g., display: block !important;), those could potentially override your x-cloak style, causing elements to flash. If you encounter FOUC even with x-cloak and its CSS rule in place, inspect the element in your browser's developer tools to see which display styles are being applied and why.
Alpine-Managed Content Area:
(This appeared after Alpine initialization. It was hidden by x-cloak until Alpine was ready.)
Initializing content... Please wait.
(If you see this, Alpine is preparing the content. x-cloak ensures you don't see a raw/unstyled version before this.)
The blue box above has the x-cloak attribute. We've also included the required CSS ([x-cloak] { display: none !important; }) in the <head> of this document.
The Alpine component deliberately introduces a small delay (1 second) before setting isReady to true and updating the message.
Without x-cloak (and its CSS): If the content inside the blue box was, for example, static HTML Text that Alpine was meant to replace, or elements styled in a way that would make them visible by default, you might briefly see that raw, uninitialized state before Alpine processes it. This is the FOUC.
With x-cloak: The entire blue box (and its initial content) is hidden by the CSS rule until AlpineJS initializes the component and removes the x-cloak attribute. Then, x-show takes over to display the appropriate message based on the isReady state. This results in a smoother user experience.