ResponsiveImage

Appearance

Fastly ​

The Fastly Image Optimizer (IO) is supported by using a helper function in the @responsive-image/cdn package.

Setup ​

Make sure you have the @responsive-image/cdn package installed:

bash
npm install @responsive-image/cdn
bash
yarn add @responsive-image/cdn
bash
pnpm add @responsive-image/cdn

You need to specify your domain in your configuration, which you can set up in your application (e.g. app.js):

js
import { setConfig } from '@responsive-image/core';

setConfig('cdn', {
  fastly: {
    domain: 'images.mydomain.com',
  },
});

INFO

By default fastly is configured to only use the webp format since avif requires a higher cost tier of Fastly IO. You can change which formats get used by default by passing defaultFormats next to domain in this configuration.

Usage ​

IMPORTANT

Please make sure you have read the section on remote images first.

Use the fastly provider function passing the pathname to the image on the CDN, and pass the return value to the image component:

gjs
import { ResponsiveImage } from '@responsive-image/ember';
import { fastly } from '@responsive-image/cdn';

<template>
  <ResponsiveImage @src={{fastly 'path/to/uploaded/image.jpg'}} />
</template>
hbs
<ResponsiveImage
  @src={{responsive-image-fastly 'path/to/uploaded/image.jpg'}}
/>
ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { fastly } from '@responsive-image/cdn';
import '@responsive-image/wc';

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<responsive-image
      .src=${fastly('path/to/uploaded/image.jpg')}
    ></responsive-image>`;
  }
}
tsx
import { ResponsiveImage } from '@responsive-image/react';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return <ResponsiveImage src={fastly('path/to/uploaded/image.jpg')} />;
}
tsx
import { ResponsiveImage } from '@responsive-image/solid';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return <ResponsiveImage src={fastly('path/to/uploaded/image.jpg')} />;
}
svelte
<script>
  import { ResponsiveImage } from '@responsive-image/svelte';
  import { fastly } from '@responsive-image/cdn';
</script>

<ResponsiveImage src={fastly('path/to/uploaded/image.jpg')} />

Aspect Ratio ​

For the image component to be able to render width and height attributes to prevent layout shifts after loading has completed, it needs to know the aspect ratio of the source image. Unlike local images it cannot know this upfront for remote images, that's why it is recommended to supply the aspectRatio parameter if possible:

gjs
import { ResponsiveImage } from '@responsive-image/ember';
import { fastly } from '@responsive-image/cdn';

<template>
  <ResponsiveImage
    @src={{fastly
      '/path/to/image.jpg'
      aspectRatio=1.5
    }}
  />
</template>
hbs
<ResponsiveImage
  @src={{responsive-image-fastly '/path/to/image.jpg' aspectRatio=1.5}}
/>
ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { fastly } from '@responsive-image/cdn';
import '@responsive-image/wc';

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<responsive-image
      .src=${fastly('/path/to/image.jpg', {
        aspectRatio: 1.5,
      })}
    ></responsive-image>`;
  }
}
tsx
import { ResponsiveImage } from '@responsive-image/react';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        aspectRatio: 1.5,
      })}
    />
  );
}
tsx
import { ResponsiveImage } from '@responsive-image/solid';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        aspectRatio: 1.5,
      })}
    />
  );
}
svelte
<script>
  import { ResponsiveImage } from '@responsive-image/svelte';
  import { fastly } from '@responsive-image/cdn';
</script>

<ResponsiveImage
  src={fastly('path/to/uploaded/image.jpg', {
    aspectRatio: 1.5,
  })}
/>

Custom parameters ​

Besides the transformations that the addon itself implicitly adds (related to resizing images) you can add your own parameters by passing a params object:

gjs
import { ResponsiveImage } from '@responsive-image/ember';
import { fastly } from '@responsive-image/cdn';

<template>
  <ResponsiveImage
    @src={{fastly
      'path/to/uploaded/image.jpg'
      params=(hash orient='l' saturation=-100)
    }}
  />
</template>
hbs
<ResponsiveImage
  @src={{responsive-image-fastly
    'path/to/uploaded/image.jpg'
    params=(hash orient='l' saturation=-100)
  }}
/>
ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { fastly } from '@responsive-image/cdn';
import '@responsive-image/wc';

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<responsive-image
      .src=${fastly('path/to/uploaded/image.jpg', {
        orient: 'l',
        saturation: -100,
      })}
    ></responsive-image>`;
  }
}
tsx
import { ResponsiveImage } from '@responsive-image/react';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        orient: 'l',
        saturation: -100,
      })}
    />
  );
}
tsx
import { ResponsiveImage } from '@responsive-image/solid';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        orient: 'l',
        saturation: -100,
      })}
    />
  );
}
svelte
<script>
  import { ResponsiveImage } from '@responsive-image/svelte';
  import { fastly } from '@responsive-image/cdn';
</script>

<ResponsiveImage
  src={fastly('path/to/uploaded/image.jpg', {
    orient: 'l',
    saturation: -100,
  })}
/>

Quality ​

Use the quality parameter to pass a custom quality setting instead of the default auto:

gjs
import { ResponsiveImage } from '@responsive-image/ember';
import { fastly } from '@responsive-image/cdn';

<template>
  <ResponsiveImage
    @src={{fastly
      'path/to/uploaded/image.jpg'
      quality=50
    }}
  />
</template>
hbs
<ResponsiveImage
  @src={{responsive-image-fastly 'path/to/uploaded/image.jpg' quality=50}}
/>
ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { fastly } from '@responsive-image/cdn';
import '@responsive-image/wc';

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<responsive-image
      .src=${fastly('path/to/uploaded/image.jpg', {
        quality: 50,
      })}
    ></responsive-image>`;
  }
}
tsx
import { ResponsiveImage } from '@responsive-image/react';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        quality: 50,
      })}
    />
  );
}
tsx
import { ResponsiveImage } from '@responsive-image/solid';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        quality: 50,
      })}
    />
  );
}
svelte
<script>
  import { ResponsiveImage } from '@responsive-image/svelte';
  import { fastly } from '@responsive-image/cdn';
</script>

<ResponsiveImage
  src={fastly('path/to/uploaded/image.jpg', {
    quality: 50,
  })}
/>

Image formats ​

By default the component uses the automatic image format selection in Fastly.

If you want a picture tag with one or more specific formats as source tags you can specify them using the formats argument:

gjs
import { ResponsiveImage } from '@responsive-image/ember';
import { fastly } from '@responsive-image/cdn';

<template>
  <ResponsiveImage
    @src={{fastly
      'path/to/uploaded/image.jpg'
      formats=(array 'webp' 'avif')
    }}
  />
</template>
hbs
<ResponsiveImage
  @src={{responsive-image-fastly
    'path/to/uploaded/image.jpg'
    formats=(array 'webp' 'avif')
  }}
/>
ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { fastly } from '@responsive-image/cdn';
import '@responsive-image/wc';

@customElement('my-app')
export class MyApp extends LitElement {
  render() {
    return html`<responsive-image
      .src=${fastly('path/to/uploaded/image.jpg', {
        formats: ['webp', 'avif'],
      })}
    ></responsive-image>`;
  }
}
tsx
import { ResponsiveImage } from '@responsive-image/react';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        formats: ['webp', 'avif'],
      })}
    />
  );
}
tsx
import { ResponsiveImage } from '@responsive-image/solid';
import { fastly } from '@responsive-image/cdn';

export default function MyApp() {
  return (
    <ResponsiveImage
      src={fastly('path/to/uploaded/image.jpg', {
        formats: ['webp', 'avif'],
      })}
    />
  );
}
svelte
<script>
  import { ResponsiveImage } from '@responsive-image/svelte';
  import { fastly } from '@responsive-image/cdn';
</script>

<ResponsiveImage
  src={fastly('path/to/uploaded/image.jpg', {
    formats: ['webp', 'avif'],
  })}
/>

INFO

See the Fastify reference documentation for a list of supported formats.

avif requires you pay for Fastly IO Professional.

Made with ❤︎ for OSS - Support 🇺🇦

Copyright © 2025 Simon Ihmig