Skip to content

Commit

Permalink
[guides/images] Streamline (old) image integration content (#3707)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sarah11918
sarah11918 authored Jul 14, 2023
1 parent 0262d1b commit e0f40c5
Showing 1 changed file with 11 additions and 227 deletions.
238 changes: 11 additions & 227 deletions src/content/docs/en/guides/images.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,12 @@ import Since from '~/components/Since.astro';

Astro provides several ways for you to use images on your site, whether they are stored locally inside your project, linked to remotely, or stored in a CMS or CDN!

:::note[using Assets (Experimental)]
Experimental asset support was added in `astro@2.1.0`. If you have enabled assets support, see the [Assets (Experimental) Guide](/en/guides/assets/) for extra information.
:::note[`astro:assets` (Experimental - coming in v3.0)]
The experimental `astro:assets` module will be enabled by default in `astro@3.0`.

**Some of the advice below is incompatible with the experimental flag.**
Follow the [Assets (Experimental) Guide](/en/guides/assets/) to start using Astro's new image solution today!

**Some of the advice below is incompatible with the experimental flag. Please see the Assets page if you are using `astro:assets`.**
:::

### In `.astro` files
Expand Down Expand Up @@ -127,242 +129,24 @@ This will require you to update your existing images, remove the current Astro i

## Astro's Image Integration

Astro's official image integration provides two different Astro components for rendering optimized images, `<Image />` and `<Picture />`. It is supported for all static sites and for [some server-side rendering deploy hosts](/en/guides/integrations-guide/image/#installation).

After [installing `@astrojs/image`](/en/guides/integrations-guide/image/#installation), you can use these two components wherever you can use Astro components: in `.astro` and `.mdx` files.

:::note[incompatible with assets]
If you have enabled experimental asset support, then you must uninstall the official integration. See the [Assets (Experimental) Guide](/en/guides/assets/) for more information.
:::

### `<Image />`

Astro's [`<Image />` component](/en/guides/integrations-guide/image/#image-) allows you to optimize a single image and specify width, height, and/or aspect ratio. You can even transform your image to a particular output format.

This component is useful for images where you want to keep a consistent size across displays, or closely control the quality of an image (e.g. logos).

For responsive images, or art direction, use the `<Picture />` component instead.

#### Remote Images

(required attributes: [`src`](/en/guides/integrations-guide/image/#src), [`alt`](/en/guides/integrations-guide/image/#alt), [`format`](/en/guides/integrations-guide/image/#format), and dimensions)

Pass a full URL to the `<Image />` component's `src` attribute and include a value for `alt`.

The `<Image />` component cannot determine the original file format of a remote image, so you must provide an output `format` (e.g. png, avif) to transform your remote image.

You must also either provide [`width`](/en/guides/integrations-guide/image/#width) and [`height`](/en/guides/integrations-guide/image/#height), or one of the dimensions plus an [`aspectRatio`](/en/guides/integrations-guide/image/#aspectratio) to avoid content layout shifts because the `<Image />` component does not know the dimensions of a remote image.

[All other properties](/en/guides/integrations-guide/image/#image-) are optional.

#### Local Images in `src/`

(required attributes: [`src`](/en/guides/integrations-guide/image/#src), and [`alt`](/en/guides/integrations-guide/image/#alt))

Import your image in frontmatter and pass it directly to the `<Image />` component's `src` attribute.

`alt` is required, but [all other properties](/en/guides/integrations-guide/image/#image-) are optional and will default to the image file's original properties if not provided.

#### Images in `public/`

(required attributes: [`src`](/en/guides/integrations-guide/image/#src), [`alt`](/en/guides/integrations-guide/image/#alt), [`format`](/en/guides/integrations-guide/image/#format), and dimensions)

Pass the component's `src` attribute a path relative to the public folder and include a value for `alt`.

It will be treated as a remote image, which requires either both [`width`](/en/guides/integrations-guide/image/#width) and [`height`](/en/guides/integrations-guide/image/#height), or one dimension and an [`aspectRatio`](/en/guides/integrations-guide/image/#aspectratio) attribute.

A value for the `format` attribute (e.g. png, avif) to transform your image is required.

[All other properties](/en/guides/integrations-guide/image/#image-) are optional.

Your original image will be copied unprocessed to the build folder, like all files located in `public/`, and Astro's image integration will also return optimized versions of the image.
:::note[to be deprecated in v3.0]
The [`@astrojs/image`](https://github.com/withastro/astro/tree/main/packages/integrations/image) integration will no longer be actively supported in Astro v3.0.

#### Examples
We suggest removing it at your earliest convenience and using the experimental `astro:assets` module which will be built in to `astro@3.0`.

```astro
---
// src/pages/index.astro
import { Image } from '@astrojs/image/components';
import localImage from "../assets/logo.png";
const remoteImage = "https://picsum.photos/id/957/300/200.jpg";
const localAlt = "The Astro Logo";
const remoteAlt = "A low-angle view of a forest during the daytime";
---
<!--optimized local image, keeping the original width, height, and image format-->
<Image src={localImage} alt={localAlt} />
<!-- height will be recalculated to match the original aspect ratio-->
<Image src={localImage} width={300} alt={localAlt} />
<!--For remote images, the desired dimensions and format are required-->
<Image src={remoteImage} width={300} aspectRatio="1:1" format="png" alt={remoteAlt} />
<!-- cropping to a specific width and height -->
<Image src={localImage} width={300} height={600} alt={localAlt}/>
<Image src={remoteImage} width={544} height={184} format="png" alt={remoteAlt}/>
<!-- cropping to a specific aspect ratio and converting to an avif format-->
<Image src={localImage} aspectRatio="16:9" format="avif" alt={localAlt}/>
<Image src={remoteImage} height={200} aspectRatio="16:9" format="avif" alt={remoteAlt}/>
<!-- local image imports can also be inlined directly-->
<Image src={import('../assets/logo.png')} alt={localAlt}/>
<!-- If an image is stored in the `/public` folder, use its path relative to `/public`-->
<Image src="/penguin.jpg" width="300" aspectRatio={1} format="png" alt="A happy penguin"/>
```

### `<Picture /> `
Follow the [Assets (Experimental) Guide](/en/guides/assets/) to start using Astro's new image solution today!

Astro's [`<Picture />` component](/en/guides/integrations-guide/image/#picture-) can be used to provide responsive images on your site, including multiple image sizes, formats, and layouts.

You can let the user's browser choose appropriate image sizes, resolutions, and file types based on factors like screen size and bandwidth. Or, you can specify rules that the browser must follow based on media queries.

This component is useful to optimize what your user sees at various screen sizes, or for art direction.

:::tip
Check out MDN's guide for more information about [responsive images and art direction](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction).
**`astro:assets` is not a complete replacement for `@astrojs/image` at this time, but it is under active development.**
:::

#### Remote Images

(required attributes: [`src`](/en/guides/integrations-guide/image/#src-1), [`widths`](/en/guides/integrations-guide/image/#widths), [`sizes`](/en/guides/integrations-guide/image/#sizes), [`alt`](/en/guides/integrations-guide/image/#alt-1), and [`aspectRatio`](/en/guides/integrations-guide/image/#aspectratio-1))

Pass a full URL to the `<Picture />` component's `src` attribute.

A value for `aspectRatio` is also required to ensure the correct height can be calculated at build time for remote images.

You must provide the component with guidance for image widths and screen sizes, but [all other properties](/en/guides/integrations-guide/image/#picture-) are optional.

Although [`formats`](/en/guides/integrations-guide/image/#formats) is not required, the original image format of remote images is unknown and will not be included by default. If not provided, only `webp` and `avif` will be included.

#### Local Images

(required attributes: [`src`](/en/guides/integrations-guide/image/#src-1), [`widths`](/en/guides/integrations-guide/image/#widths), [`sizes`](/en/guides/integrations-guide/image/#sizes), [`alt`](/en/guides/integrations-guide/image/#alt-1))

Import your image in frontmatter and pass it directly to the `<Picture />` component's `src` attribute.

You must provide the component with guidance for image widths and screen sizes, but [all other properties](/en/guides/integrations-guide/image/#picture-) are optional.

By default, the `<Picture />` component's [`formats`](/en/guides/integrations-guide/image/#formats) will include `avif` and `webp` in addition to the image's original format if not specified.

#### Images in `public/`

(required attributes: [`src`](/en/guides/integrations-guide/image/#src-1), [`widths`](/en/guides/integrations-guide/image/#widths), [`sizes`](/en/guides/integrations-guide/image/#sizes), [`alt`](/en/guides/integrations-guide/image/#alt-1), and [`aspectRatio`](/en/guides/integrations-guide/image/#aspectratio-1))

Pass the component's `src` attribute a path relative to the public folder and include a value for `alt`.

The image will be treated as a remote image, so a value for `aspectRatio` is also required to ensure the correct height can be calculated at build time.

You must provide the component with guidance for image widths and screen sizes, but [all other properties](/en/guides/integrations-guide/image/#picture-) are optional.

Although [`formats`](/en/guides/integrations-guide/image/#formats) is not required, the original image format of images in the `public/` folder is unknown and will not be included by default. If not provided, only `webp` and `avif` will be included.

Your original image will be copied unprocessed to the build folder, like all files located in `public/`, and Astro's image integration will also return optimized versions of the image.

#### Examples

```astro
---
import { Picture } from '@astrojs/image/components';
import localImage from '../assets/logo.png';
const remoteImage = 'https://docs.astro.build/assets/full-logo-light.png';
---
<!--Local image with multiple sizes and formats-->
<Picture src={localImage} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" formats={['avif', 'jpeg', 'png', 'webp']} alt="The Astro logo" />
<!--Remote image (aspect ratio is required)-->
<Picture src={remoteImage} widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="The Google logo" />
<!--Images in /public work like remote images-->
<Picture src="/logo.png" widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="The Google logo" />
<!--Inlined imports are supported-->
<Picture src={import("../assets/logo.png")} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="The Astro logo" />
```


### Using in MDX

In `.mdx` files, `<Image />` and `<Picture />` can receive your image `src` through imports and exports.

```mdx
// src/pages/index.mdx
import { Image, Picture } from '@astrojs/image/components';
import rocket from '../assets/rocket.png';
export const logo = 'https://docs.astro.build/assets/full-logo-light.png';
<Image src={import('../assets/galaxy.png')} alt="Outer space."/>
<Image src={rocket} width={300} alt="Spaceship approaching the moon."/>
<Picture src={rocket} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="A rocket blasting off." />
<Picture src={logo} widths={[200, 400, 800]} aspectRatio={16/9} sizes="(max-width: 800px) 100vw, 800px" alt="The full Astro logo." />
```

### Setting Default Values

Currently, there is no way to specify default values for all `<Image />` and `<Picture />` components. Required attributes should be set on each individual component.

As an alternative, you can wrap these components in another Astro component for reuse. For example, you could create a component for your blog post images:

```astro title="src/components/BlogPostImage.astro"
---
import { Picture } from '@astrojs/image/components';
const {src, ...attrs} = Astro.props;
---
<Picture src={src} widths={[400, 800, 1500]} sizes="(max-width: 767px) 100vw, 736px" {...attrs} />
<style>
img, picture :global(img), svg {
margin-block: 2.5rem;
border-radius: 0.75rem;
}
</style>
```

### Using `<img>` with the Image Integration

The official image integration will change image imports to return an object rather than a source string.
The object has the following properties, derived from the imported file:
```ts
{
src: string;
width: number;
height: number;
format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp';
}
```

If you have the image integration installed, refer to the `src` property of the object when using `<img>`.

```astro ".src"
---
import rocket from '../images/rocket.svg';
---
<img src={rocket.src} alt="A rocketship in space."/>
```

Alternatively, add `?url` to your imports to tell them to return a source string.

```astro "?url"
---
import rocket from '../images/rocket.svg?url';
---
<img src={rocket} alt="A rocketship in space."/>
```
For documentation on using `@astrojs/image` in Astro v2, please see the [`@astrojs/image` package documentation](https://github.com/withastro/astro/blob/main/packages/integrations/image/README.md)

## Using Images from a CMS or CDN

Image CDNs work with Astro. Use an image's full URL as the `src` attribute in an `<img>` tag or Markdown notation.

Alternatively, if the CDN provides a Node.js SDK, you can use that in your project. For example, [Cloudinary’s SDK](https://cloudinary.com/documentation/node_integration) can generate the `<img>` tag with the appropriate `src` for you.

To use [external images with the `<Image />`](#remote-images) and [`<Picture />`](#remote-images-1) components from Astro's image integration, you must specify the appropriate dimension and format values for working with remote images.

## Alt Text

Not all users can see images in the same way, so accessibility is an especially important concern when using images. Use the `alt` attribute to provide [descriptive alt text](https://www.w3.org/WAI/tutorials/images/) for images.
Expand Down

0 comments on commit e0f40c5

Please sign in to comment.