Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Styling and Assets

Scoped Styles and Global CSS in Astro

Style Astro components with scoped CSS, escape to global styles with is:global, pass values with define:vars and build class names with class:list.

Every Astro component can carry its own CSS in a <style> tag. By default that CSS is scoped: it only touches the elements written in that component. You can name your classes .title or .card everywhere without collisions, and you do not need CSS Modules, BEM discipline or a CSS-in-JS library to get that safety.

This lesson explains how scoping works, how to deliberately break out of it, how to hand values from the component script to CSS, and how to build class lists without string gymnastics.

Scoped styles by default

Put a <style> block anywhere in the template part of a .astro file:

ASTRO
---
const { title } = Astro.props;
---
<article class="card">
  <h2>{title}</h2>
  <slot />
</article>

<style>
  .card {
    border: 1px solid #d0d7de;
    border-radius: 12px;
    padding: 1rem 1.25rem;
  }
  h2 {
    margin: 0 0 0.5rem;
    font-size: 1.25rem;
  }
</style>

The h2 rule does not restyle every h2 on the site. At build time Astro adds a generated class such as astro-J7PV25F6 to each element of this component and rewrites your selectors so they only match elements carrying it. The emitted rule looks like h2:where(.astro-J7PV25F6). The :where() wrapper has zero specificity, so scoping never makes your selectors harder to override than you wrote them.

Scoping is a compile-time feature. Nothing runs in the browser to make it work, so it costs no JavaScript and no runtime.

What scoping does not reach

Scoped styles apply to elements written in this component's own template. They do not reach:

  • Content a child component renders inside its own template.
  • Markup that arrives through <slot /> from a parent (the parent owns those elements and their scope class).
  • HTML you inject with set:html.

If a scoped selector "does nothing", one of those three is usually the reason. The fixes are below.

Breaking out: :global and is:global

To style a child component's output you can wrap a selector part in :global():

ASTRO
<style>
  .prose :global(a) {
    color: royalblue;
    text-decoration-thickness: 2px;
  }
  .prose :global(code) {
    background: #f3f4f6;
    padding: 0.1em 0.3em;
  }
</style>

Only the wrapped part loses its scope class. The .prose part is still scoped, so these rules apply only to links and code inside this component's .prose element, including markup coming from slots. This is the pattern for Markdown wrappers and layouts.

If the whole block should be global, use the is:global directive:

ASTRO
<style is:global>
  :root {
    --brand: #6d28d9;
    color-scheme: light dark;
  }
  body {
    margin: 0;
    font-family: system-ui, sans-serif;
  }
</style>

Use is:global sparingly: in a root layout for resets, variables and base typography. Everything else should stay scoped.

Importing CSS files

For shared stylesheets, import a file in the component frontmatter. Astro bundles and minifies it, and only the pages that use that component receive it:

ASTRO
---
import '../styles/reset.css';
import '../styles/tokens.css';
---

You can also import from npm packages (import 'some-lib/style.css') or link a file from public/ with a plain <link>; the latter is not processed or hashed, so prefer imports.

Astro uses Vite for CSS, so @import and url() references inside imported files are resolved, and CSS Modules (styles.module.css) work if you like that style:

ASTRO
---
import styles from './Button.module.css';
---
<button class={styles.primary}>Save</button>

define:vars: JavaScript values in CSS

Sometimes a color or size comes from props or data. define:vars turns frontmatter variables into CSS custom properties on the element scope:

ASTRO
---
const { hue = 220, size = 48 } = Astro.props;
---
<div class="avatar">AB</div>

<style define:vars={{ hue, size }}>
  .avatar {
    --bg: hsl(var(--hue) 70% 85%);
    width: calc(var(--size) * 1px);
    height: calc(var(--size) * 1px);
    background: var(--bg);
    border-radius: 50%;
    display: grid;
    place-items: center;
  }
</style>

define:vars on a <style> tag makes it behave like is:inline: the style is no longer bundled, it is emitted as is. That is fine for a few rules; keep big stylesheets out of such blocks.

class:list

Conditional classes are common, so Astro ships class:list. It accepts strings, arrays, objects (key is the class, value is a condition) and falsy values:

ASTRO
---
const { variant = 'solid', disabled = false } = Astro.props;
---
<button
  class:list={[
    'btn',
    `btn-${variant}`,
    { 'is-disabled': disabled },
    disabled && 'no-pointer',
  ]}
  disabled={disabled}
>
  <slot />
</button>

It de-duplicates classes and drops empty values, so you will never print class="btn undefined false" again.

Try it: how scoping works

This stand-in is not Astro's compiler. It reproduces the idea: derive a short hash from the component name, add it to each element, and rewrite selectors into selector:where(.astro-hash).

JS A tiny CSS scoper

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that .prose :global(a) becomes .prose a: it lost the scope class on purpose. In the real compiler the .prose part would still be scoped; the stand-in keeps the whole selector global for brevity.

Try it: class:list

Here is a faithful stand-in for the way class:list flattens its input.

JS Build class:list

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Keep component CSS in the component. Move to a shared file only when two or more components need the same tokens.
  • Define design tokens (colors, spacing) as CSS variables in one is:global block or imported file, then use var(--token) everywhere.
  • Prefer classes over bare element selectors inside components, so a later markup change does not silently match more or fewer elements.
  • Reach for :global() only on the specific child part you need.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Astro do to a rule like h2 { margin: 0 } in a component's <style>?

    Scoping is the default. The compiler adds a generated class to the component's elements and narrows the selector with :where(), at build time.
  2. 2. A parent passes content through <slot /> and your scoped rule does not style it. Which fix keeps the rule limited to this component?

    Wrapping only the target part in :global() removes the scope class from that part while the scoped parent selector keeps the rule contained.
  3. 3. What is define:vars for?

    define:vars exposes JavaScript values to CSS as custom properties. The style then behaves as inline, so it is not bundled.
  4. 4. What does class:list={['a', { b: false, c: true }, null]} produce?

    Object keys are included only when their value is truthy and falsy entries such as null are dropped, leaving a and c.

Summary

  • <style> in a .astro file is scoped by default through a generated class and a zero-specificity :where().
  • Scoping does not reach child component internals, slotted content or set:html output.
  • :global() opens a hole in one selector; is:global makes the entire block global.
  • Import CSS files in the frontmatter; they are bundled and minified.
  • define:vars passes values to CSS; class:list builds clean class strings.

Next: Tailwind and Sass in Astro