Styles & CSS
Astro was designed to make styling and writing CSS a breeze. Write your own CSS directly inside of an Astro component or import your favorite CSS library like Tailwind. Advanced styling languages like Sass and Less are also supported.
Styling in Astro
Section titled Styling in AstroStyling an Astro component is as easy as adding a <style>
tag to your component or page template. When you place a <style>
tag inside of an Astro component, Astro will detect the CSS and handle your styles for you, automatically.
<style>
h1 { color: red; }
</style>
Scoped Styles
Section titled Scoped StylesAstro <style>
CSS rules are automatically scoped by default. Scoped styles are compiled behind-the-scenes to only apply to HTML written inside of that same component. The CSS that you write inside of an Astro component is automatically encapsulated inside of that component.
<style>
h1 { color: red; }
h1:where(.astro-HHNQFKH6) { color: red; }
.text { color: blue; }
.text:where(.astro-HHNQFKH6) { color: blue; }
</style>
Scoped styles don’t leak and won’t impact the rest of your site. In Astro, it is okay to use low-specificity selectors like h1 {}
or p {}
because they will be compiled with scopes in the final output.
Scoped styles also won’t apply to other Astro components contained inside of your template. If you need to style a child component, consider wrapping that component in a <div>
(or other element) that you can then style.
The specificity of scoped styles is preserved, allowing them to work consistently alongside other CSS files or CSS libraries while still preserving the exclusive boundaries that prevent styles from applying outside the component.
Global Styles
Section titled Global StylesWhile we recommend scoped styles for most components, you may eventually find a valid reason to write global, unscoped CSS. You can opt-out of automatic CSS scoping with the <style is:global>
attribute.
<style is:global>
/* Unscoped, delivered as-is to the browser.
Applies to all <h1> tags on your site. */
h1 { color: red; }
</style>
You can also mix global & scoped CSS rules together in the same <style>
tag using the :global()
selector. This becomes a powerful pattern for applying CSS styles to children of your component.
<style>
/* Scoped to this component, only. */
h1 { color: red; }
/* Mixed: Applies to child `h1` elements only. */
article :global(h1) {
color: blue;
}
</style>
<h1>Title</h1>
<article><slot /></article>
This is a great way to style things like blog posts, or documents with CMS-powered content where the contents live outside of Astro. But be careful: components whose appearance differs based on whether or not they have a certain parent component can become difficult to troubleshoot.
Scoped styles should be used as often as possible. Global styles should be used only as-needed.
Combining classes with class:list
Section titled Combining classes with class:listIf you need to combine classes on an element dynamically, you can use the class:list
utility attribute in .astro
files.
---
const { isRed } = Astro.props;
---
<!-- If `isRed` is truthy, class will be "box red". -->
<!-- If `isRed` is falsy, class will be "box". -->
<div class:list={['box', { red: isRed }]}><slot /></div>
<style>
.box { border: 1px solid blue; }
.red { border-color: red; }
</style>
📚 See our directives reference page to learn more about class:list
.
CSS Variables
Section titled CSS VariablesThe Astro <style>
can reference any CSS variables available on the page. You can also pass CSS variables directly from your component front matter using the define:vars
directive.
---
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
---
<style define:vars={{ foregroundColor, backgroundColor }}>
h1 {
background-color: var(--backgroundColor);
color: var(--foregroundColor);
}
</style>
<h1>Hello</h1>
📚 See our directives reference page to learn more about define:vars
.
Passing a class
to a child component
Section titled Passing a class to a child componentIn Astro, HTML attributes like class
do not automatically pass through to child components.
Instead, accept a class
prop in the child component and apply it to the root element. When destructuring, you must rename it, because class
is a reserved word in JavaScript.
---
const { class: className } = Astro.props;
---
<div class={className}>
<slot/>
</div>
---
import MyComponent from "../components/MyComponent.astro"
---
<style>
.red {
color: red;
}
</style>
<MyComponent class="red">This will be red!</MyComponent>
This pattern lets you style child components directly. Astro will pass the parent’s scoped class name (e.g. astro-HHNQFKH6
) through the class
prop automatically, including the child in its parent’s scope.
External Styles
Section titled External StylesThere are two ways to resolve external global stylesheets: an ESM import for files located within your project source, and an absolute URL link for files in your public/
directory, or hosted outside of your project.
📚 Read more about using static assets located in public/
or src/
.
Import a local stylesheet
Section titled Import a local stylesheetYou can import stylesheets in your Astro component front matter using ESM import syntax. CSS imports work like any other ESM import in an Astro component, which should be referenced as relative to the component and must be written at the top of your component script, with any other imports.
---
// Astro will bundle and optimize this CSS for you automatically
// This also works for preprocessor files like .scss, .styl, etc.
import '../styles/utils.css';
---
<html><!-- Your page here --></html>
CSS import
via ESM are supported inside of any JavaScript file, including JSX components like React & Preact. This can be useful for writing granular, per-component styles for your React components.
Import a stylesheet from an npm package
Section titled Import a stylesheet from an npm packageYou may also need to load stylesheets from an external npm package. This is especially common for utilities like Open Props. If your package recommends using a file extension (i.e. package-name/styles.css
instead of package-name/styles
), this should work like any local stylesheet:
---
import 'package-name/styles.css';
---
<html><!-- Your page here --></html>
If your package does not suggest using a file extension (i.e. package-name/styles
), you’ll need to update your Astro config first!
Say you are importing a CSS file from package-name
called normalize
(with the file extension omitted). To ensure we can prerender your page correctly, add package-name
to the vite.ssr.noExternal
array:
import { defineConfig } from 'astro/config';
export default defineConfig({
vite: {
ssr: {
noExternal: ['package-name'],
}
}
})
Now, you are free to import package-name/normalize
. This will be bundled and optimized by Astro like any other local stylesheet.
---
import 'package-name/normalize';
---
<html><!-- Your page here --></html>
Load a static stylesheet via “link” tags
Section titled Load a static stylesheet via “link” tagsYou can also use the <link>
element to load a stylesheet on the page. This should be an absolute URL path to a CSS file located in your /public
directory, or an URL to an external website. Relative <link>
href values are not supported.
<head>
<!-- Local: /public/styles/global.css -->
<link rel="stylesheet" href="/styles/global.css" />
<!-- External -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism-tomorrow.css" />
</head>
Because this approach uses the public/
directory, it skips the normal CSS processing, bundling and optimizations that are provided by Astro. If you need these transformations, use the Import a Stylesheet method above.
Cascading Order
Section titled Cascading OrderAstro components will sometimes have to evaluate multiple sources of CSS. For example, your component might import a CSS stylesheet, include its own <style>
tag, and be rendered inside a layout that imports CSS.
When conflicting CSS rules apply to the same element, browsers first use specificity and then order of appearance to determine which value to show.
If one rule is more specific than another, no matter where the CSS rule appears, its value will take precedence:
<style>
h1 { color: red }
div > h1 {
color: purple
}
</style>
<div>
<h1>
This header will be purple!
</h1>
</div>
If two rules have the same specificity, then the order of appearance is evaluated, and the last rule’s value will take precedence:
<style>
h1 { color: purple }
h1 { color: red }
</style>
<div>
<h1>
This header will be red!
</h1>
</div>
Astro CSS rules are evaluated in this order of appearance:
<link>
tags in the head (lowest precedence)- imported styles
- scoped styles (highest precedence)
Scoped Styles
Section titled Scoped StylesUsing scoped styles does not increase the specificity of your CSS, but they will always come last in the order of appearance. They will therefore take precedence over other styles of the same specificity. For example, if you import a stylesheet that conflicts with a scoped style, the scoped style’s value will apply:
h1 {
color: purple;
}
---
import "./make-it-purple.css"
---
<style>
h1 { color: red }
</style>
<div>
<h1>
This header will be red!
</h1>
</div>
If you make the imported style more specific, it will have higher precedence over the scoped style:
div > h1 {
color: purple;
}
---
import "./make-it-purple.css"
---
<style>
h1 { color: red }
</style>
<div>
<h1>
This header will be purple!
</h1>
</div>
Import Order
Section titled Import OrderWhen importing multiple stylesheets in an Astro component, the CSS rules are evaluated in the order that they are imported. A higher specificity will always determine which styles to show, no matter when the CSS is evaluated. But, when conflicting styles have the same specificity, the last one imported wins:
div > h1 {
color: purple;
}
div > h1 {
color: green;
}
---
import "./make-it-green.css"
import "./make-it-purple.css"
---
<style>
h1 { color: red }
</style>
<div>
<h1>
This header will be purple!
</h1>
</div>
While <style>
tags are scoped and only apply to the component that declares them, imported CSS can “leak”. Importing a component applies any CSS it imports, even if the component is never used:
---
import "./make-it-purple.css"
---
<div>
<h1>I import purple CSS.</h1>
</div>
---
import "./make-it-green.css"
import PurpleComponent from "./PurpleComponent.astro";
---
<style>
h1 { color: red }
</style>
<div>
<h1>
This header will be purple!
</h1>
</div>
Link Tags
Section titled Link TagsStyle sheets loaded via link tags are evaluated in order, before any other styles in an Astro file. Therefore, these styles will have lower precedence than imported stylesheets and scoped styles:
---
import "../components/make-it-purple.css"
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content={Astro.generator} />
<title>Astro</title>
<link rel="stylesheet" href="/styles/make-it-blue.css" />
</head>
<body>
<div>
<h1>This will be purple</h1>
</div>
</body>
</html>
CSS Integrations
Section titled CSS IntegrationsAstro comes with support for adding popular CSS libraries, tools and frameworks to your project like Tailwind and more!
📚 See the Integrations Guide for instructions on installing, importing and configuring these integrations.
CSS Preprocessors
Section titled CSS PreprocessorsAstro supports CSS preprocessors such as Sass, Stylus, and Less through Vite.
Sass and SCSS
Section titled Sass and SCSSnpm install -D sass
Use <style lang="scss">
or <style lang="sass">
in .astro
files
Stylus
Section titled Stylusnpm install -D stylus
Use <style lang="styl">
or <style lang="stylus">
in .astro
files
npm install -D less
Use <style lang="less">
in .astro
files.
In framework components
Section titled In framework componentsYou can also use all of the above CSS preprocessors within JS frameworks as well! Be sure to follow the patterns each framework recommends:
- React / Preact:
import Styles from './styles.module.scss'
; - Vue:
<style lang="scss">
- Svelte:
<style lang="scss">
PostCSS
Section titled PostCSSAstro comes with PostCSS included as part of Vite. To configure PostCSS for your project, create a postcss.config.cjs
file in the project root. You can import plugins using require()
after installing them (for example npm install autoprefixer
).
module.exports = {
plugins: [
require('autoprefixer'),
require('cssnano'),
],
};
Frameworks and Libraries
Section titled Frameworks and Libraries📘 React / Preact
Section titled 📘 React / Preact.jsx
files support both global CSS and CSS Modules. To enable the latter, use the .module.css
extension (or .module.scss
/.module.sass
if using Sass).
import './global.css'; // include global CSS
import Styles from './styles.module.css'; // Use CSS Modules (must end in `.module.css`, `.module.scss`, or `.module.sass`!)
📗 Vue
Section titled 📗 VueVue in Astro supports the same methods as vue-loader
does:
📕 Svelte
Section titled 📕 SvelteSvelte in Astro also works exactly as expected: Svelte Styling Docs.
Advanced
Section titled Advanced?raw
CSS Imports
Section titled ?raw CSS ImportsFor advanced use cases, CSS can be read directly from disk without being bundled or optimized by Astro. This can be useful when you need complete control over some snippet of CSS, and need to bypass Astro’s automatic CSS handling.
This is not recommended for most users.
---
// Advanced example! Not recommended for most users.
import rawStylesCSS from '../styles/main.css?raw';
---
<style is:inline set:html={rawStylesCSS}></style>
See Vite’s docs for full details.
?url
CSS Imports
Section titled ?url CSS ImportsFor advanced use cases, you can import a direct URL reference for a CSS file inside of your project src/
directory. This can be useful when you need complete control over how a CSS file is loaded on the page. However, this will prevent the optimization of that CSS file with the rest of your page CSS .
This is not recommended for most users. Instead, place your CSS files inside of public/
to get a consistent URL reference.
---
// Advanced example! Not recommended for most users.
import stylesUrl from '../styles/main.css?url';
---
<link rel="preload" href={stylesUrl} as="style">
<link rel="stylesheet" href={stylesUrl}>
See Vite’s docs for full details.