Imágenes

Astro proporciona varias formas de usar imágenes en tu sitio, ya sea que estén almacenadas localmente dentro de tu proyecto, enlazadas desde una URL externa o gestionadas en un CMS o CDN.

Astro proporciona componentes de Astro integrados <Image /> y <Picture />, procesamiento de la sintaxis de imagen de Markdown (![]()), componentes SVG y una función de generación de imágenes para optimizar y/o transformar tus imágenes. Además, puedes configurar el redimensionamiento automático de imágenes responsivas por defecto, o establecer propiedades responsivas en componentes individuales de imagen y picture.

Siempre puedes optar por utilizar imágenes y archivos SVG usando elementos HTML nativos en archivos .astro o Markdown, o de la manera estándar para tu tipo de archivo (p. ej., <img /> en MDX y JSX). Sin embargo, Astro no realiza ningún procesamiento ni optimización de estas imágenes.

Tampoco hay soporte nativo de video en Astro, y recomendamos elegir un servicio de video alojado para manejar las demandas de optimización y transmisión de contenido de video.

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Dónde almacenar las imágenes

`src/` vs `public/`

Recomendamos que las imágenes locales se guarden en src/ cuando sea posible para que Astro pueda transformarlas, optimizarlas y empaquetarlas. Los archivos en el directorio public/ siempre se sirven o se copian en la carpeta de compilación tal cual, sin ningún procesamiento.

Tus imágenes locales almacenadas en src/ pueden ser utilizadas por todos los archivos de tu proyecto: .astro, .md, .mdx, .mdoc y otros frameworks de UI como importaciones de archivos. Las imágenes se pueden almacenar en cualquier carpeta, incluso junto a tu contenido.

Almacena tus imágenes en la carpeta public/ si quieres evitar cualquier procesamiento. Estas imágenes están disponibles para los archivos de tu proyecto como rutas URL en tu dominio y te permiten tener un enlace público directo a ellas. Por ejemplo, el favicon de tu sitio comúnmente se colocará en la raíz de esta carpeta donde los navegadores puedan identificarlo.

Imágenes remotas

También puedes optar por almacenar tus imágenes de forma remota, en un sistema de gestión de contenidos (CMS) o en una plataforma de gestión de activos digitales (DAM). Astro puede recuperar tus datos de forma remota utilizando APIs o mostrar imágenes desde su ruta URL completa.

Para mayor protección al tratar con fuentes externas, los componentes de imagen de Astro y la función auxiliar solo procesarán (p. ej., optimizarán, transformarán) imágenes de fuentes de imágenes autorizadas especificadas en tu configuración. Las imágenes remotas de otras fuentes se mostrarán sin procesamiento.

Imágenes en archivos `.astro`

Opciones: <Image />, <Picture />, <img>, <svg>, componentes SVG

El lenguaje de plantillas de Astro te permite renderizar imágenes optimizadas con el componente <Image /> de Astro y generar múltiples tamaños y formatos con el componente <Picture /> de Astro. Ambos componentes también aceptan propiedades de imagen responsiva para cambiar el tamaño según el tamaño del contenedor y responder al tamaño y resolución de la pantalla del dispositivo.

Además, puedes importar y usar archivos SVG como componentes de Astro en componentes .astro.

Todas las etiquetas HTML nativas, incluyendo <img> and <svg>, también están disponibles en los componentes .astro. Las imágenes renderizadas con etiquetas HTML no serán procesadas (p. ej., optimizadas, transformadas) y se copiarán en tu carpeta de compilación tal cual.

Para todas las imágenes en archivos .astro, el valor del atributo src de la imagen se determina por la ubicación de tu archivo de imagen:

Una imagen local de la carpeta src/ de tu proyecto utiliza una importación desde la ruta relativa del archivo.

Los componentes de imagen y picture utilizan la importación nombrada directamente (p. ej., src={rocket}), mientras que la etiqueta <img> utiliza la propiedad de objeto src de la importación (p. ej., src={rocket.src}).
Las imágenes remotas y en public/ utilizan una ruta URL.

Proporciona una URL completa para imágenes remotas (p. ej., src="https://www.example.com/images/my-remote-image.jpg"), o una ruta URL relativa en tu sitio que corresponda a la ubicación de tu archivo en tu carpeta public/ (p. ej., src="/images/my-public-image.jpg" para una imagen ubicada en public/images/my-public-image.jpg).

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />, incluidas las propiedades obligatorias y opcionales.

Related recipe: Importar imágenes dinámicamente

Imágenes en archivos Markdown

Opciones: ![](), <img> (con imágenes públicas o remotas)

Utiliza la sintaxis estándar de Markdown ![alt](src) en tus archivos .md. Tus imágenes locales almacenadas en src/ e imágenes remotas serán procesadas y optimizadas. Cuando configuras imágenes responsivas globalmente, estas imágenes también serán responsivas.

Las imágenes almacenadas en la carpeta public/ nunca se optimizan.

# My Markdown Page

<!-- Local image stored in src/assets/ -->
<!-- Use a relative file path or import alias -->
![A starry night sky.](../assets/stars.png)

<!-- Image stored in public/images/ -->
<!-- Use the file path relative to public/ -->
![A starry night sky.](/images/stars.png)

<!-- Remote image on another server -->
<!-- Use the full URL of the image -->
![Astro](https://example.com/images/remote-image.png)

La etiqueta HTML <img> también se puede usar para mostrar imágenes almacenadas en public/ o imágenes remotas sin ninguna optimización o procesamiento de imagen. Sin embargo, <img> no es compatible con tus imágenes locales en src.

Los componentes <Image /> y <Picture /> no están disponibles en archivos .md. Si necesitas más control sobre los atributos de tus imágenes, recomendamos usar la integración MDX de Astro para agregar soporte para el formato de archivo .mdx. MDX permite opciones de imagen adicionales disponibles en MDX, incluyendo la combinación de componentes con la sintaxis de Markdown.

Imágenes en archivos MDX

Opciones: <Image />, <Picture />, <img />, ![](), componentes SVG

Puedes usar los componentes <Image /> y <Picture /> de Astro en tus archivos .mdx importando tanto el componente como tu imagen. Úsalos exactamente como se usan en los archivos .astro. La etiqueta JSX <img /> también es compatible para imágenes no procesadas y utiliza la misma importación de imagen que la etiqueta HTML <img>.

Además, hay soporte para la sintaxis estándar de Markdown ![alt](src) sin necesidad de importación.

---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# My MDX Page

// Local image stored in the same folder
![Houston in the wild](houston.png)

// Local image stored in src/assets/
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)

// Image stored in public/images/
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)

// Remote image on another server
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Imágenes en componentes de frameworks de UI

Opciones de imagen: la propia sintaxis de imagen del framework (p. ej., <img /> en JSX, <img> en Svelte)

Las imágenes locales primero deben ser importadas para acceder a sus propiedades de imagen como src. Luego, se pueden renderizar como lo harías normalmente en la propia sintaxis de imagen de ese framework:

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="A starry night sky." />
  )
}

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="A starry night sky." />

Los componentes de Astro (p. ej., <Image />, <Picture />, componentes SVG) no están disponibles dentro de los componentes de frameworks de UI porque una isla de cliente debe contener únicamente código válido para su propio framework.

Pero puedes pasar el contenido estático generado por estos componentes a un componente de framework dentro de un archivo .astro como hijos o usando un slot con nombre <slot/>:

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="A starry night sky." />
</ReactComponent>

Componentes de Astro para imágenes

Astro proporciona dos componentes de Astro integrados para imágenes (<Image /> y <Picture />) y también te permite importar archivos SVG y usarlos como componentes de Astro. Estos componentes pueden usarse en cualquier archivo que pueda importar y renderizar componentes .astro.

`<Image />`

Utiliza el componente de Astro integrado <Image /> para mostrar versiones optimizadas de:

tus imágenes locales ubicadas dentro de la carpeta src/
imágenes remotas configuradas de fuentes autorizadas

<Image /> puede transformar las dimensiones, el tipo de archivo y la calidad de una imagen local o remota autorizada para tener control sobre la imagen mostrada. Esta transformación ocurre en el momento de la compilación para las páginas pre-renderizadas. Cuando tu página se renderiza bajo demanda, esta transformación ocurrirá sobre la marcha cuando se visualice la página. La etiqueta <img> resultante incluye los atributos alt, loading y decoding e infiere las dimensiones de la imagen para evitar la Inestabilidad del Diseño Acumulada (CLS).

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description of my image." />

<!-- Prerendered output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

<!-- Output rendered on demand-->
<!-- src will use an endpoint generated on demand-->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

El componente <Image /> acepta varias propiedades de componente, así como cualquier atributo aceptado por la etiqueta HTML <img>.

El siguiente ejemplo proporciona una clase (class) al componente de imagen que se aplicará al elemento <img> final.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="" class="my-class" />

<!-- Prerendered output -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

`<Picture />`

Añadido en: astro@3.3.0

Utiliza el componente de Astro integrado <Picture /> para generar una etiqueta <picture> con múltiples formatos y/o tamaños de tu imagen. Esto te permite especificar los formatos de archivo preferidos a mostrar y, al mismo tiempo, proporcionar un formato alternativo. Al igual que el componente <Image />, las imágenes se procesarán en el momento de la compilación para las páginas pre-renderizadas. Cuando tu página se renderiza bajo demanda, el procesamiento ocurrirá sobre la marcha cuando se visualice la página.

El siguiente ejemplo utiliza el componente <Picture /> para transformar un archivo .png local en los formatos avif y webp compatibles con la web, así como la etiqueta .png <img> que se puede mostrar como alternativa cuando sea necesario:

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---

<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- Prerendered output -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

Consulta los detalles sobre las propiedades del componente <Picture /> en la referencia de astro:assets.

Comportamiento de imagen responsivo

Añadido en: astro@5.10.0

Las imágenes responsivas son imágenes que se ajustan para mejorar el rendimiento en diferentes dispositivos. Estas imágenes pueden cambiar de tamaño para adaptarse a su contenedor y pueden servirse en diferentes tamaños según el tamaño de la pantalla y la resolución de tu visitante.

Con la propiedad layout aplicada a los componentes <Image /> o <Picture />, Astro generará automáticamente los valores srcset y sizes necesarios para tus imágenes, y aplicará los estilos necesarios para asegurar que se redimensionen correctamente.

Cuando este comportamiento responsivo se configura globalmente con image.layout, se aplicará a todos los componentes de imagen y también a cualquier imagen local y remota que utilice la sintaxis de Markdown ![]().

Las imágenes de tu carpeta public/ nunca se optimizan, y las imágenes responsivas no son compatibles.

Lee más sobre imágenes responsivas en MDN web docs.

Salida HTML generada para imágenes responsivas

Cuando se establece un diseño (layout), ya sea de forma predeterminada o en un componente individual, las imágenes tienen atributos srcset y sizes generados automáticamente según las dimensiones de la imagen y el tipo de diseño. Las imágenes con diseños constrained y full-width tendrán estilos aplicados para asegurar que se redimensionen de acuerdo con su contenedor.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />

Este componente <Image /> generará la siguiente salida HTML en una página pre-renderizada:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

Estilos de imágenes responsivas

Establecer image.responsiveStyles: true aplica una pequeña cantidad de estilos globales para asegurar que tus imágenes se redimensionen correctamente. En la mayoría de los casos, querrás habilitar esto de forma predeterminada; tus imágenes no serán responsivas sin estilos adicionales.

Sin embargo, si prefieres manejar el estilo de las imágenes responsivas tú mismo, o necesitas anular estos valores predeterminados al usar Tailwind 4, deja configurado el valor predeterminado false.

Los estilos globales aplicados por Astro dependerán del tipo de diseño (layout) y están diseñados para producir el mejor resultado para los atributos srcset y sizes generados. Estos son los estilos predeterminados:

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

Los estilos utilizan la pseudo-clase :where(), que tiene una especificidad de 0, lo que significa que es fácil de anular con tus propios estilos. Cualquier selector CSS tendrá una especificidad mayor que :where(), por lo que puedes anular fácilmente los estilos agregando tus propios estilos para apuntar a la imagen.

Puedes anular los estilos object-fit y object-position para cada imagen de forma individual estableciendo las props fit y position en el componente <Image /> o <Picture />.

Imágenes responsivas con Tailwind 4

Tailwind 4 es compatible con los estilos responsivos predeterminados de Astro. Sin embargo, Tailwind utiliza capas de cascada (cascade layers), lo que significa que sus reglas siempre tienen una especificidad menor que las reglas que no utilizan capas, incluidos los estilos responsivos de Astro. Por lo tanto, el estilo de Astro tendrá prioridad sobre el estilo de Tailwind. Para usar las reglas de Tailwind en lugar del estilo predeterminado de Astro, no habilites los estilos responsivos predeterminados de Astro.

Componentes SVG

Añadido en: astro@5.7.0

Astro te permite importar archivos SVG y usarlos como componentes de Astro. Astro incrustará el contenido SVG en tu salida HTML.

Haz referencia a la importación predeterminada de cualquier archivo .svg local. Dado que esta importación se trata como un componente de Astro, debes usar las mismas convenciones (p. ej., mayúsculas) que al usar etiquetas dinámicas.

---
import Logo from './path/to/svg/file.svg';
---

<Logo />

Tu componente SVG, al igual que <Image /> o cualquier otro componente de Astro, no está disponible dentro de los componentes de frameworks de UI, pero puede ser pasado a un componente de framework dentro de un componente .astro.

Atributos del componente SVG

Puedes pasar props como width, height, fill, stroke y cualquier otro atributo aceptado por el elemento <svg> nativo. Estos atributos se aplicarán automáticamente al elemento <svg> subyacente. Si una propiedad está presente en el archivo .svg original y se pasa al componente, el valor pasado al componente anulará el valor original.

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

Tipo `SvgComponent`

Añadido en: astro@5.14.0

También puedes aplicar la seguridad de tipos para tus activos .svg utilizando el tipo SvgComponent:

---
import type { SvgComponent } from "astro/types";
import HomeIcon from "./Home.svg";

interface Link {
  url: string;
  text: string;
  icon: SvgComponent;
}

const links: Link[] = [
  {
    url: "/",
    text: "Home",
    icon: HomeIcon,
  },
];
---

Creación de componentes de imagen personalizados

Puedes crear un componente de imagen personalizado y reutilizable envolviendo el componente <Image /> o <Picture/> en otro componente de Astro. Esto te permite establecer atributos y estilos predeterminados una sola vez.

Por ejemplo, podrías crear un componente para las imágenes de las publicaciones de tu blog que reciba atributos como props y aplique estilos consistentes a cada imagen:

---
import { Image } from "astro:assets";

const { alt, src, ...attrs } = Astro.props;
---

<Image alt={alt} src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

Mostrar imágenes no procesadas con la etiqueta HTML `<img>`

La sintaxis de plantilla de Astro también admite escribir una etiqueta <img> directamente, con control total sobre su salida final. Estas imágenes no se procesarán ni optimizarán. Acepta todas las propiedades de la etiqueta HTML <img>, y la única propiedad requerida es src. Sin embargo, se recomienda encarecidamente incluir la propiedad alt por accesibilidad.

imágenes en `src/`

Las imágenes locales deben importarse desde la ruta relativa del archivo .astro existente, o puedes configurar y utilizar un alias de importación. Luego, puedes acceder al src de la imagen y a otras propiedades para usarlas en la etiqueta <img>.

Los recursos de imagen importados coinciden con el tipo ImageMetadata y tienen la siguiente firma:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

El siguiente ejemplo utiliza las propias propiedades height y width de la imagen para evitar la Inestabilidad del Diseño Acumulada (CLS) y mejorar las Core Web Vitals:

---
// import local images
import myDog from '../../images/pets/local-dog.jpg';
---
// access the image properties
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="A barking dog." />

Imágenes en `public/`

Para las imágenes ubicadas dentro de public/, utiliza la ruta del archivo de la imagen relativa a la carpeta public como el valor de src:

<img src="/images/public-cat.jpg" alt="A sleeping cat." >

Imágenes remotas

Para las imágenes remotas, utiliza la URL completa de la imagen como el valor de src:

<img src="https://example.com/remote-cat.jpg" alt="A sleeping cat." >

Elegir `<Image />` vs `<img>`

El componente <Image /> optimiza tu imagen e infiere el ancho (width) y el alto (height) (para las imágenes que puede procesar) en función de la relación de aspecto original para evitar el CLS. Es la forma preferida de usar imágenes en archivos .astro siempre que sea posible.

Utiliza el elemento HTML <img> cuando no puedas usar el componente <Image />, por ejemplo:

para formatos de imagen no admitidos
cuando no deseas que Astro optimice tu imagen
para acceder y cambiar el atributo src de forma dinámica en el lado del cliente

Uso de imágenes de un CMS o CDN

Las CDNs de imágenes funcionan con todas las opciones de imágenes de Astro. Utiliza la URL completa de una imagen como atributo src en el componente <Image />, en una etiqueta <img> o en la notación de Markdown. Para la optimización de imágenes con imágenes remotas, también debes configurar tus dominios autorizados o patrones de URL.

Alternativamente, la CDN puede proporcionar sus propios SDKs para integrarse más fácilmente en un proyecto de Astro. Por ejemplo:

Cloudinary admite un Astro SDK que te permite colocar fácilmente imágenes con su componente CldImage o un Node.js SDK que puede generar URLs para usar con una etiqueta <img> en un entorno Node.js.
ImageKit proporciona una integración de Astro que registra un servicio de imágenes. Esto significa que los componentes integrados de Astro <Image /> y <Picture />, junto con las imágenes Markdown ![]() y MDX, se dirigen automáticamente a través de ImageKit. Agrega entrega por CDN, conversión automática AVIF/WebP, srcset responsivo y transformaciones sobre la marcha sin cambiar tu sintaxis de imagen existente.

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Autorización de imágenes remotas

Puedes configurar listas de dominios y patrones de URL de origen de imágenes autorizadas para la optimización de imágenes utilizando image.domains e image.remotePatterns. Esta configuración es una capa adicional de seguridad para proteger tu sitio al mostrar imágenes de una fuente externa.

Las imágenes remotas de otras fuentes no se optimizarán, pero el uso del componente <Image /> para estas imágenes evitará la Inestabilidad del Diseño Acumulada (CLS).

Por ejemplo, la siguiente configuración solo permitirá optimizar imágenes remotas de astro.build:

export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

La siguiente configuración solo permitirá imágenes remotas de hosts HTTPS:

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Imágenes en colecciones de contenido

Puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una publicación de blog, en tu frontmatter utilizando su ruta relativa a la carpeta actual:

---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # will resolve to "src/content/blog/firstpostcover.jpeg"
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post

El ayudante image para el esquema de colecciones de contenido te permite validar e importar la imagen.

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

La imagen se importará y se transformará en metadatos, lo que te permitirá pasarla como src a <Image/>, <img> o getImage() en un componente de Astro.

El siguiente ejemplo muestra una página de índice de blog que renderiza la foto de portada y el título de cada publicación de blog del esquema anterior:

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
  allBlogPosts.map((post) => (
    <div>
      <Image src={post.data.cover} alt={post.data.coverAlt} />
      <h2>
        <a href={"/blog/" + post.id}>{post.data.title}</a>
      </h2>
    </div>
  ))
}

Generación de imágenes con `getImage()`

La función getImage() está diseñada para generar imágenes destinadas a ser utilizadas en otro lugar que no sea directamente en HTML, por ejemplo en una Ruta de la API. Cuando necesites opciones que los componentes <Picture> y <Image> no admiten actualmente, puedes usar la función getImage() para crear tu propio componente <Image /> personalizado.

La función getImage() solo se puede usar en el servidor. Si necesitas usar la URL de la imagen resultante en el cliente (p. ej., en un script del lado del cliente o componente de framework), llama a getImage() dentro del frontmatter y pasa el src resultante al cliente:

---
import { getImage } from "astro:assets";
import myBackground from "../background.png";

const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background")?.dataset.src;
  // use src client-side as needed
</script>

Consulta más detalles en la referencia de getImage().

Related recipe: Construir un componente de imagen personalizado

Texto alternativo (alt)

No todos los usuarios pueden ver las imágenes de la misma manera, por lo que la accesibilidad es una preocupación especialmente importante al usar imágenes. Utiliza el atributo alt para proporcionar texto alternativo descriptivo para las imágenes.

Este atributo es obligatorio tanto para el componente <Image /> como para el componente <Picture />. Si no se proporciona texto alternativo, se mostrará un mensaje de error útil recordándote incluir el atributo alt.

Si la imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que los lectores de pantalla sepan que deben ignorar la imagen.

Servicio de imágenes predeterminado

Sharp es el servicio de imágenes predeterminado utilizado para astro:assets. Puedes configurar aún más el servicio de imágenes utilizando la opción image.service.

Configurar servicio de transferencia sin operaciones (no-op passthrough)

Si tu adaptador no es compatible con la optimización de imágenes Sharp integrada de Astro (p. ej., Cloudflare), puedes configurar un servicio de imágenes sin operaciones (no-op) para permitirte usar los componentes <Image /> y <Picture />. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de las otras ventajas de usar astro:assets, incluyendo la ausencia de Inestabilidad del Diseño Acumulada (CLS), el atributo alt obligatorio y una experiencia de autoría consistente.

Configura el passthroughImageService() para evitar el procesamiento de imágenes Sharp:

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Almacenamiento en caché de activos

Astro almacena los recursos de imágenes procesados en un directorio de caché durante las compilaciones del sitio, tanto para imágenes locales como para imágenes remotas de fuentes autorizadas. Al preservar el directorio de caché entre compilaciones, los recursos procesados se reutilizan, mejorando el tiempo de compilación y el uso del ancho de banda.

El directorio de caché predeterminado es ./node_modules/.astro, sin embargo, esto se puede cambiar utilizando el ajuste de configuración cacheDir.

Imágenes remotas

Las imágenes remotas en la caché de activos se gestionan en función del almacenamiento en caché HTTP y respetan la cabecera Cache-Control devuelta por el servidor remoto. Las imágenes se almacenan en caché si la cabecera Cache-Control lo permite, y se utilizarán hasta que dejen de estar frescas.

Revalidación

Añadido en: astro@5.1.0

La revalidación reduce el uso de ancho de banda y el tiempo de compilación al verificar con el servidor remoto si una imagen almacenada en caché que ha caducado sigue estando actualizada. Si el servidor indica que la imagen aún está fresca, se reutiliza la versión almacenada en caché; de lo contrario, la imagen se vuelve a descargar.

La revalidación requiere que el servidor remoto envíe cabeceras Last-Modified y/o Etag (etiqueta de entidad) con sus respuestas. Esta característica está disponible para servidores remotos que admitan las cabeceras If-Modified-Since e If-None-Match.

Integraciones de la comunidad

Existen varias integraciones de imágenes de la comunidad de terceros para optimizar y trabajar con imágenes en tu proyecto de Astro.

Contribuir Comunidad Patrocinar

Imágenes

Dónde almacenar las imágenes

src/ vs public/

Imágenes remotas

Imágenes en archivos .astro

Imágenes en archivos Markdown

Imágenes en archivos MDX

Imágenes en componentes de frameworks de UI

Componentes de Astro para imágenes

<Image />

<Picture />

Comportamiento de imagen responsivo

Salida HTML generada para imágenes responsivas

Estilos de imágenes responsivas

Imágenes responsivas con Tailwind 4

Componentes SVG

Atributos del componente SVG

Tipo SvgComponent

Creación de componentes de imagen personalizados

Mostrar imágenes no procesadas con la etiqueta HTML <img>

imágenes en src/

Imágenes en public/

Imágenes remotas

Elegir <Image /> vs <img>

Uso de imágenes de un CMS o CDN

Autorización de imágenes remotas

Imágenes en colecciones de contenido

Generación de imágenes con getImage()

Texto alternativo (alt)

Servicio de imágenes predeterminado

Configurar servicio de transferencia sin operaciones (no-op passthrough)

Almacenamiento en caché de activos

Imágenes remotas

Revalidación

Integraciones de la comunidad

`src/` vs `public/`

Imágenes en archivos `.astro`

`<Image />`

`<Picture />`

Tipo `SvgComponent`

Mostrar imágenes no procesadas con la etiqueta HTML `<img>`

imágenes en `src/`

Imágenes en `public/`

Elegir `<Image />` vs `<img>`

Generación de imágenes con `getImage()`