Estilos y CSS

Astro fue diseñado para hacer que dar estilo y escribir CSS sea muy fácil. Escribe tu propio CSS directamente dentro de un componente de Astro o importa tu librería CSS favorita como Tailwind. Los lenguajes de estilos avanzados como Sass y Less también son compatibles.

Estilos en Astro

Dar estilo a un componente de Astro es tan fácil como añadir una etiqueta <style> a tu componente o plantilla de página. Cuando colocas una etiqueta <style> dentro de un componente de Astro, Astro detectará el CSS y manejará tus estilos automáticamente.

src/components/MyComponent.astro

<style>
  h1 { color: red; }
</style>

Estilos scoped

Las reglas CSS de <style> de Astro se limitan automáticamente por defecto. Los estilos scoped se compilan en segundo plano para aplicarse solo al HTML escrito dentro de ese mismo componente. El CSS que escribes dentro de un componente de Astro se encapsula automáticamente dentro de ese componente.

Este CSS:

src/pages/index.astro

<style>
  h1 {
    color: red;
  }

  .text {
    color: blue;
  }
</style>

Se compila a esto:

<style>
  h1[data-astro-cid-hhnqfkh6] {
     color: red;
  }

  .text[data-astro-cid-hhnqfkh6] {
    color: blue;
  }
</style>

Los estilos scoped no se filtran y no impactarán el resto de tu sitio. En Astro, está bien usar selectores de baja especificidad como h1 {} o p {} porque se compilarán con scopes en la salida final.

Los estilos scoped tampoco se aplicarán a otros componentes de Astro contenidos dentro de tu plantilla. Si necesitas dar estilo a un componente hijo, considera envolver ese componente en un <div> (u otro elemento) que luego puedas estilizar.

La especificidad de los estilos scoped se preserva, permitiéndoles funcionar de manera consistente junto a otros archivos CSS o librerías CSS mientras se preservan los límites exclusivos que evitan que los estilos se apliquen fuera del componente.

Estilos globales

Aunque recomendamos estilos scoped para la mayoría de componentes, eventualmente puedes encontrar una razón válida para escribir CSS global sin scope. Puedes excluirte del scoping automático de CSS con el atributo <style is:global>.

src/components/GlobalStyles.astro

<style is:global>
  /* Unscoped, delivered as-is to the browser.
     Applies to all <h1> tags on your site. */
  h1 { color: red; }
</style>

También puedes mezclar reglas CSS globales y scoped juntas en la misma etiqueta <style> usando el selector :global(). Esto se convierte en un patrón poderoso para aplicar estilos CSS a los hijos de tu componente.

src/components/MixedStyles.astro

<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>

Esta es una excelente manera de dar estilo a cosas como publicaciones de blog, o documentos con contenido gestionado por CMS donde los contenidos viven fuera de Astro. Pero ten cuidado: los componentes cuya apariencia difiere según si tienen o no un determinado componente padre pueden volverse difíciles de solucionar.

Los estilos scoped deberían usarse tan a menudo como sea posible. Los estilos globales deberían usarse solo cuando sea necesario.

Combinar clases con class:list

Si necesitas combinar clases en un elemento dinámicamente, puedes usar el atributo utilitario class:list en archivos .astro.

src/components/ClassList.astro

---
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>

Consulta nuestra página de referencia de directivas para saber más sobre class:list.

Variables CSS

Añadido en: astro@0.21.0

El <style> de Astro puede referenciar cualquier variable CSS disponible en la página. También puedes pasar variables CSS directamente desde el frontmatter de tu componente usando la directiva define:vars.

src/components/DefineVars.astro

---
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>

Consulta nuestra página de referencia de directivas para saber más sobre define:vars.

Pasar una class a un componente hijo

En Astro, los atributos HTML como class no se pasan automáticamente a los componentes hijos.

En su lugar, acepta una prop class en el componente hijo y aplícala al elemento raíz. Al desestructurar, debes renombrarla, porque class es una palabra reservada en JavaScript.

Usando la estrategia de estilo scoped por defecto, también debes pasar el atributo data-astro-cid-*. Puedes hacer esto pasando el ...rest de las props al componente. Si has cambiado scopedStyleStrategy a 'class' o 'where', la prop ...rest no es necesaria.

src/components/MyComponent.astro

---
const { class: className, ...rest } = Astro.props;
---
<div class={className} {...rest}>
  <slot/>
</div>

src/pages/index.astro

---
import MyComponent from "../components/MyComponent.astro"
---
<style>
  .red {
    color: red;
  }
</style>
<MyComponent class="red">This will be red!</MyComponent>

Estilos scoped de componentes padres

Como el atributo data-astro-cid-* incluye al hijo en el scope de su padre, es posible que los estilos se propaguen del padre al hijo. Para evitar que esto tenga efectos secundarios no deseados, asegúrate de usar nombres de clase únicos en el componente hijo.

Estilos inline

Puedes dar estilo a elementos HTML inline usando el atributo style. Esto puede ser un string CSS o un objeto de propiedades CSS:

src/pages/index.astro

// These are equivalent:
<p style={{ color: "brown", textDecoration: "underline" }}>My text</p>
<p style="color: brown; text-decoration: underline;">My text</p>

Estilos externos

Hay dos formas de resolver hojas de estilos globales externas: una importación ESM para archivos ubicados dentro del código fuente de tu proyecto, y un link de URL absoluta para archivos en tu directorio public/, o alojados fuera de tu proyecto.

Lee más sobre el uso de assets estáticos ubicados en public/ o src/.

Importar una hoja de estilos local

¿Usas un paquete npm?

Puede que necesites actualizar tu astro.config al importar desde paquetes npm. Consulta la sección “importar hojas de estilos desde un paquete npm” a continuación.

Puedes importar hojas de estilos en el frontmatter de tu componente de Astro usando la sintaxis de importación ESM. Las importaciones de CSS funcionan como cualquier otra importación ESM en un componente de Astro, que debería referenciarse como relativa al componente y debe escribirse en la parte superior del script de tu componente, con cualquier otra importación.

src/pages/index.astro

---
// 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>

La importación CSS vía ESM es compatible dentro de cualquier archivo JavaScript, incluyendo componentes JSX como React y Preact. Esto puede ser útil para escribir estilos granulares por componente para tus componentes de React.

Importar una hoja de estilos desde un paquete npm

También puedes necesitar cargar hojas de estilos desde un paquete npm externo. Esto es especialmente común para utilidades como Open Props. Si tu paquete recomienda usar una extensión de archivo (p. ej. package-name/styles.css en lugar de package-name/styles), esto debería funcionar como cualquier hoja de estilos local:

src/pages/random-page.astro

---
import 'package-name/styles.css';
---
<html><!-- Your page here --></html>

Si tu paquete no sugiere usar una extensión de archivo (p. ej. package-name/styles), ¡necesitarás actualizar tu configuración de Astro primero!

Digamos que estás importando un archivo CSS desde package-name llamado normalize (con la extensión de archivo omitida). Para asegurar que podemos pre-renderizar tu página correctamente, añade package-name al array vite.ssr.noExternal:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    ssr: {
      noExternal: ['package-name'],
    }
  }
})

Nota

Esto es una configuración específica de Vite que no se relaciona con (ni requiere) Astro SSR.

Ahora, puedes importar libremente package-name/normalize. Esto será procesado y optimizado por Astro como cualquier otra hoja de estilos local.

src/pages/random-page.astro

---
import 'package-name/normalize';
---
<html><!-- Your page here --></html>

Cargar una hoja de estilos estática vía etiquetas “link”

También puedes usar el elemento <link> para cargar una hoja de estilos en la página. Esta debería ser una ruta de URL absoluta a un archivo CSS ubicado en tu directorio /public, o una URL a un sitio web externo. Los valores href relativos en <link> no son compatibles.

src/pages/index.astro

<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>

Como este enfoque usa el directorio public/, omite el procesamiento normal de CSS, bundling y optimizaciones que proporciona Astro. Si necesitas estas transformaciones, usa el método Importar una hoja de estilos de arriba.

Orden de cascada

Los componentes de Astro a veces tendrán que evaluar múltiples fuentes de CSS. Por ejemplo, tu componente podría importar una hoja de estilos CSS, incluir su propia etiqueta <style>, y renderizarse dentro de un layout que importa CSS.

Cuando reglas CSS conflictivas se aplican al mismo elemento, los navegadores primero usan especificidad y luego orden de aparición para determinar qué valor mostrar.

Si una regla es más específica que otra, sin importar dónde aparezca la regla CSS, su valor tendrá precedencia:

src/components/MyComponent.astro

<style>
  h1 { color: red }
  div > h1 {
    color: purple
  }
</style>
<div>
  <h1>
    This header will be purple!
  </h1>
</div>

Si dos reglas tienen la misma especificidad, entonces se evalúa el orden de aparición, y el valor de la última regla tendrá precedencia:

src/components/MyComponent.astro

<style>
  h1 { color: purple }
  h1 { color: red }
</style>
<div>
  <h1>
    This header will be red!
  </h1>
</div>

Las reglas CSS de Astro se evalúan en este orden de aparición:

• etiquetas <link> en el head (menor precedencia)
• imported styles
• estilos scoped (mayor precedencia)

Estilos scoped

Dependiendo del valor elegido para scopedStyleStrategy, los estilos scoped pueden o no aumentar la especificidad de la columna CLASS.

Sin embargo, los estilos scoped siempre vendrán últimos en el orden de aparición. Por lo tanto, estos estilos tendrán precedencia sobre otros estilos de la misma especificidad. Por ejemplo, si importas una hoja de estilos que conflictúa con un estilo scoped, el valor del estilo scoped se aplicará:

src/components/make-it-purple.css

h1 {
  color: purple;
}

src/components/MyComponent.astro

---
import "./make-it-purple.css"
---
<style>
  h1 { color: red }
</style>
<div>
  <h1>
    This header will be red!
  </h1>
</div>

Los estilos scoped se sobrescribirán si el estilo importado es más específico. El estilo con mayor especificidad tendrá precedencia sobre el estilo scoped:

src/components/make-it-purple.css

#intro {
  color: purple;
}

src/components/MyComponent.astro

---
import "./make-it-purple.css"
---
<style>
  h1 { color: red }
</style>
<div>
  <h1 id="intro">
    This header will be purple!
  </h1>
</div>

Orden de importación

Al importar múltiples hojas de estilos en un componente de Astro, las reglas CSS se evalúan en el orden en que se importan. Una mayor especificidad siempre determinará qué estilos mostrar, sin importar cuándo se evalúe el CSS. Pero, cuando estilos conflictivos tienen la misma especificidad, el último importado gana:

src/components/make-it-purple.css

div > h1 {
  color: purple;
}

src/components/make-it-green.css

div > h1 {
  color: green;
}

src/components/MyComponent.astro

---
import "./make-it-green.css"
import "./make-it-purple.css"
---
<style>
  h1 { color: red }
</style>
<div>
  <h1>
    This header will be purple!
  </h1>
</div>

Mientras que las etiquetas <style> son scoped y solo se aplican al componente que las declara, el CSS importado puede “filtrarse”. Importar un componente aplica cualquier CSS que importe, incluso si el componente nunca se usa:

src/components/PurpleComponent.astro

---
import "./make-it-purple.css"
---
<div>
  <h1>I import purple CSS.</h1>
</div>

src/components/MyComponent.astro

---
import "./make-it-green.css"
import PurpleComponent from "./PurpleComponent.astro";
---
<style>
  h1 { color: red }
</style>
<div>
  <h1>
    This header will be purple!
  </h1>
</div>

Consejo

Un patrón común en Astro es importar CSS global dentro de un componente layout. Asegúrate de importar el componente layout antes que otras importaciones para que tenga la menor precedencia.

Etiquetas Link

Las hojas de estilos cargadas vía etiquetas link se evalúan en orden, antes que cualquier otro estilo en un archivo de Astro. Por lo tanto, estos estilos tendrán menor precedencia que las hojas de estilos importadas y los estilos scoped:

src/pages/index.astro

---
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>

Tailwind

Astro incluye soporte para añadir librerías CSS populares, herramientas, y frameworks a tu proyecto como Tailwind y más.

Astro soporta tanto Tailwind 3 como 4. Puedes añadir soporte para Tailwind 4 a través de un plugin de Vite a tu proyecto con un comando CLI, o instalar las dependencias legacy manualmente para añadir soporte para Tailwind 3 a través de una integración de Astro.

Para actualizar tu proyecto de Astro de Tailwind 3 a 4 necesitarás tanto añadir soporte para Tailwind 4, como eliminar el soporte legacy de Tailwind 3.

Añadir Tailwind 4

En Astro >=5.2.0, usa el comando astro add tailwind para tu gestor de paquetes para instalar el plugin oficial de Vite para Tailwind. Para añadir soporte de Tailwind 4 a versiones anteriores de Astro, sigue las instrucciones en la documentación de Tailwind para añadir el plugin de Vite @tailwindcss/vite manualmente.

npm

npx astro add tailwind

pnpm

pnpm astro add tailwind

Yarn

yarn astro add tailwind

Luego, importa tailwindcss en src/styles/global.css (u otro archivo CSS de tu elección) para hacer las clases de Tailwind disponibles en tu proyecto de Astro. Este archivo incluyendo la importación será creado por defecto si usaste el comando astro add tailwind para instalar el plugin de Vite.

src/styles/global.css

@import "tailwindcss";

Importa este archivo en las páginas donde quieras que Tailwind se aplique. Esto se suele hacer en un componente layout para que los estilos de Tailwind puedan usarse en todas las páginas que compartan ese layout:

src/layouts/Layout.astro

---
import "../styles/global.css";
---

Actualizar desde Tailwind 3

Sigue los pasos para actualizar un proyecto de Astro existente que use Tailwind v3 (usando la integración @astrojs/tailwind) a Tailwind 4 (usando el plugin @tailwindcss/vite).

1. Añade soporte para Tailwind 4 a tu proyecto a través del CLI para la última versión de Astro, o añadiendo el plugin de Vite manualmente.

2. Desinstala la integración @astrojs/tailwind de tu proyecto:

   npm

   npm uninstall @astrojs/tailwind

   pnpm

   pnpm remove @astrojs/tailwind

   Yarn

   yarn remove @astrojs/tailwind

3. Elimina la integración @astrojs/tailwind de tu astro.config.mjs:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import tailwind from '@astrojs/tailwind';
   
   export default defineConfig({
     // ...
     integrations: [tailwind()],
     // ...
   });

4. Luego, actualiza tu proyecto según la guía de actualización de Tailwind v4.

Soporte legacy de Tailwind 3

Para añadir (o mantener) soporte para Tailwind 3, necesitarás tener tanto tailwindcss@3 como la integración oficial de Tailwind para Astro @astrojs/tailwind instalados. Instalar estas dependencias manualmente solo se usa para compatibilidad legacy con Tailwind 3, y no es necesario para Tailwind 4. También necesitarás una configuración legacy de Tailwind:

1. Instala Tailwind y la integración de Tailwind para Astro en las dependencias de tu proyecto usando tu gestor de paquetes preferido:

   npm

   npm install tailwindcss@3 @astrojs/tailwind

   pnpm

   pnpm add tailwindcss@3 @astrojs/tailwind

   Yarn

   yarn add tailwindcss@3 @astrojs/tailwind

2. Importa la integración a tu archivo astro.config.mjs, y añádela a tu array integrations[]:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import tailwind from '@astrojs/tailwind';
   
   export default defineConfig({
     // ...
     integrations: [tailwind()],
     // ...
   });

3. Crea un archivo tailwind.config.mjs en el directorio raíz de tu proyecto. Puedes usar el siguiente comando para generar un archivo de configuración básico:

   npm

   npx tailwindcss init

   pnpm

   pnpm dlx tailwindcss init

   Yarn

   yarn dlx tailwindcss init

4. Añade la siguiente configuración básica a tu archivo tailwind.config.mjs:

   tailwind.config.mjs

   /** @type {import('tailwindcss').Config} */
   export default {
     content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
     theme: {
       extend: {},
     },
     plugins: [],
   };

Related recipe: Estilizar Markdown renderizado con Tailwind Typography

Preprocesadores CSS

Astro soporta preprocesadores CSS como Sass, Stylus, y Less a través de Vite.

Sass y SCSS

npm install sass

Usa <style lang="scss"> o <style lang="sass"> en archivos .astro.

Stylus

npm install stylus

Usa <style lang="styl"> o <style lang="stylus"> en archivos .astro.

Less

npm install less

Usa <style lang="less"> en archivos .astro.

LightningCSS

npm install lightningcss

Actualiza tu configuración de vite en astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    css: {
      transformer: "lightningcss",
    },
  },
})

En componentes de framework

¡También puedes usar todos los preprocesadores CSS anteriores dentro de frameworks JS! Asegúrate de seguir los patrones que cada framework recomienda:

• React / Preact: import Styles from './styles.module.scss';
• Vue: <style lang="scss">
• Svelte: <style lang="scss">

PostCSS

Astro incluye PostCSS como parte de Vite. Para configurar PostCSS para tu proyecto, crea un archivo postcss.config.cjs en la raíz del proyecto. Puedes importar plugins usando require() después de instalarlos (por ejemplo npm install autoprefixer).

postcss.config.cjs

module.exports = {
  plugins: [
    require('autoprefixer'),
    require('cssnano'),
  ],
};

Frameworks y librerías

📘 React / Preact

Los archivos .jsx soportan tanto CSS global como CSS Modules. Para habilitar este último, usa la extensión .module.css (o .module.scss/.module.sass si usas Sass).

src/components/MyReactComponent.jsx

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

Vue en Astro soporta los mismos métodos que vue-loader:

• vue-loader - Scoped CSS
• vue-loader - CSS Modules

📕 Svelte

Svelte en Astro también funciona exactamente como se espera: Documentación de estilos de Svelte.

Estilos en Markdown

Cualquier método de estilos de Astro está disponible para un componente layout de Markdown, pero diferentes métodos tendrán diferentes efectos de estilo en tu página.

Puedes aplicar estilos globales a tu contenido de Markdown añadiendo hojas de estilos importadas al layout que envuelve el contenido de tu página. También es posible dar estilo a tu Markdown con etiquetas <style is:global> en el componente layout. Ten en cuenta que cualquier estilo añadido está sujeto al orden de cascada de Astro, y deberías revisar tu página renderizada cuidadosamente para asegurar que tus estilos se están aplicando como intended.

También puedes añadir integraciones de CSS incluyendo Tailwind. Si estás usando Tailwind, el plugin de tipografía puede ser útil para dar estilo a Markdown.

Producción

Control de bundle

Cuando Astro construye tu sitio para despliegue en producción, minifica y combina tu CSS en chunks. Cada página de tu sitio obtiene su propio chunk, y además, el CSS que se comparte entre múltiples páginas se divide además en sus propios chunks para reutilización.

Sin embargo, cuando tienes varias páginas compartiendo estilos, algunos chunks compartidos pueden volverse muy pequeños. Si todos se enviaran por separado, llevaría a muchas peticiones de hojas de estilos y afectaría el rendimiento del sitio. Por lo tanto, por defecto Astro enlazará solo aquellos en tu HTML por encima de 4kB de tamaño como etiquetas <link rel="stylesheet">, mientras que inserta los más pequeños inline en <style type="text/css">. Este enfoque proporciona un equilibrio entre el número de peticiones adicionales y el volumen de CSS que puede cachearse entre páginas.

Puedes configurar el tamaño en el que las hojas de estilos se enlazarán externamente (en bytes) usando la opción de build assetsInlineLimit de Vite. Ten en cuenta que esta opción también afecta la inserción inline de scripts e imágenes.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    build: {
      assetsInlineLimit: 1024,
    }
  }
});

Si prefieres que todos los estilos del proyecto permanezcan externos, puedes configurar la opción de build inlineStylesheets.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  build: {
    inlineStylesheets: 'never'
  }
});

También puedes establecer esta opción en 'always' lo que insertará todas las hojas de estilos inline.

Avanzado

Precaución

¡Ten cuidado al omitir el bundling de CSS integrado de Astro! Los estilos no se incluirán automáticamente en la salida del build, y es tu responsabilidad asegurarte de que el archivo referenciado se incluya correctamente en la salida final de la página.

Importaciones CSS ?raw

Para casos de uso avanzados, el CSS puede leerse directamente del disco sin ser procesado u optimizado por Astro. Esto puede ser útil cuando necesitas control completo sobre algún fragmento de CSS, y necesitas omitir el manejo automático de CSS de Astro.

Esto no es recomendado para la mayoría de usuarios.

src/components/RawInlineStyles.astro

---
// Advanced example! Not recommended for most users.
import rawStylesCSS from '../styles/main.css?raw';
---
<style is:inline set:html={rawStylesCSS}></style>

Consulta la documentación de Vite para más detalles.

Importaciones CSS ?url

Para casos de uso avanzados, puedes importar una referencia de URL directa para un archivo CSS dentro del directorio src/ de tu proyecto. Esto puede ser útil cuando necesitas control completo sobre cómo se carga un archivo CSS en la página. Sin embargo, esto evitará la optimización de ese archivo CSS con el resto del CSS de tu página.

Esto no es recomendado para la mayoría de usuarios. En su lugar, coloca tus archivos CSS dentro de public/ para obtener una referencia de URL consistente.

Precaución

Importar un archivo CSS más pequeño con ?url puede devolver los contenidos codificados en base64 del archivo CSS como una URL de datos en tu build final. Escribe tu código para soportar URLs de datos codificadas (data:text/css;base64,...) o establece la opción de configuración vite.build.assetsInlineLimit en 0 para deshabilitar esta característica.

src/components/RawStylesUrl.astro

---
// 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}>

Consulta la documentación de Vite para más detalles.