CSS that hides content

A reveal has to hide its content before it can show it. That gives the CSS two jobs the rest of a snippet’s styles do not have: it must apply before the first paint, and it must let go if the script that ends the hidden state never runs.

Load the CSS in the head

Scripts run late. A module script is deferred, so the browser has usually painted the HTML from the server before it executes. A rule that arrives with the script hides content the reader has already seen: the image shows, vanishes, then comes back. That flash is worse than no effect.

So every snippet ships its CSS as a file, and every version loads it in the head:

1
---
2
// Imported in the frontmatter, so Astro bundles it into the head.
3
import "../styles/word-wipe.css";
4
---
5

6
<div data-word-wipe>
7
  <slot />
8
</div>
9

10
<script>
11
  import { initWordWipes } from "../scripts/word-wipe";
12
  initWordWipes();
13
</script>

1
// A CSS import: the bundler puts it in the head before the text paints.
2
import "../styles/word-wipe.css";

A snippet that hides nothing, such as marquee or pixelate-image, loads its CSS the same way. Nothing would flash if it arrived late, but one rule for every snippet is easier to follow than two.

Never hide content on CSS alone

Head CSS that hides content can fail in its own way: if the script never runs, the content stays hidden. The snippets guard against that in three ways. Use the first where you can, and the other two together where the hiding has to start at first paint.

1. Hide only once the script has claimed the element. word-wipe dims text only when it has data-word-wipe-state="pending", which the script sets. Without the script the attribute never appears, and the text shows at full strength.
2. Hide only when scripting is on. block-image-reveal and scroll-reveal must hide from first paint, so their rules sit inside @media (scripting: enabled). With JavaScript switched off, the rules do not apply. The same query adds (prefers-reduced-motion: no-preference), so nothing is hidden for people who opt out of motion.
3. Add a failsafe for a script that fails to load. Scripting can be on and the file can still fail to arrive. While the element has no state attribute, a CSS animation with a three second delay sets the content back to visible. The script sets a state as soon as it runs, which switches the failsafe off.

1
@media (scripting: enabled) and (prefers-reduced-motion: no-preference) {
2
  /* Hidden until the panel carries it in, unless the script stood down. */
3
  [data-block-image-reveal]:not([data-block-image-reveal-state="off"])
4
    > :not([data-block-image-reveal-panel]) {
5
    opacity: 0;
6
  }
7

8
  /* The script has not claimed the element after 3s, so show the content. */
9
  [data-block-image-reveal]:not([data-block-image-reveal-state])
10
    > :not([data-block-image-reveal-panel]) {
11
    animation: block-image-reveal-failsafe 0s 3s forwards;
12
  }
13
}

A browser that does not know the scripting query skips the whole block. The content then shows from the start and the effect plays over it, which is a fair result for an old browser.

Scope it, don’t layer it

Leave snippet CSS out of cascade layers, and scope every rule to the snippet’s data-* attributes. A snippet goes into projects you don’t control, and many of them have an unlayered reset. Unlayered CSS beats every layer whatever its specificity, so a rule such as svg { display: block } would undo a layered snippet. Scoped rules beat a reset’s element rules on specificity. The project changes the look through the snippet’s custom properties, not by overriding its rules.

Which guard to use