Nuxt 3.x

nuxt-cover

Thanks to the open source TwicPics Components, delivering responsive images in your Nuxt3 projects has never been easier.

Installation

Requirement

The only requirement is to have a TwicPics account. If you don't already have one, you can easily create your own TwicPics account for free.

Installing @twicpics/components into your project

You just need to add the @twicpics/components npm package to your project.

Simply type one of:

npm install @twicpics/components

or

yarn add @twicpics/components

depending on which package manager you fancy.

Setup

Setting-up TwicPics Components into your Nuxt 3.x project

TwicPics components for Nuxt3 comes as an Nuxt3 Module and is configured as such.

nuxt.config.ts

Add @twicpics/components/nuxt3 to the modules section

With your twicpics configuration

export default defineNuxtConfig({
  modules: [`@twicpics/components/nuxt3`],
  twicpics: {
    domain: `https://<your-domain>.twic.pics`,
  },
})
// here is an example of a `nuxt.config.ts` configured with TwicPics.
import { defineNuxtConfig } from 'nuxt'

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
  modules: [`@twicpics/components/nuxt3`],
  twicpics: {
    domain: `https://<your-domain>.twic.pics`,
    anticipation: 0.5,
    step: 50,
  },
})

Setup Options

OptionDescriptionTypeDefault
anticipationTwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting.Number0.2
domainThis is your very own TwicPics domain. Providing it is mandatory.String
envCan be debug, offline or production. When set to debug, a gray lightweight svg placeholder that displays its intrinsic dimensions is displayed in place of all medias targeted by their src value. When set to offline, these medias are replaced by a simple placeholder that allows to visualise their display area.String"production"
maxDPRTwicPics will take the "Device Pixel Ratio" (DPR) of the current device into consideration when determining the sizes of images to load. By default, it will not take a DPR greater than 2 into consideration. If the DPR of the device is higher than 2, TwicPics will assume it to be 2. Using maxDPR, you can lower this limit down to 1 or be more permissive (for instance by setting it to 3 or 4).Number2
pathPath to prepend to all src attributes. For instance, if path is "some/folder" then a src attribute set to "image.jpg" will be expanded into "some/folder/image.jpg"String
stepTo avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio.Integer10

Usage

TwicImg and TwicVideo are available in your templates as long as you have configured the TwicPics Nuxt3 Module.

Just use them in your template files in place of img or video tags (see Components Properties).

<template>
  <main>
    <TwicImg src="path/to/your/image" />
  </main>
</template>

Basic usage

<your-page-or-component>.vue

<template>
  <main>
    <TwicImg src="path/to/your/image" />
  </main>
</template>

Style-Driven Approach

You can set up components using pure CSS and the power of CSS variables

<your-page-or-component>.vue

<template>
  <main>
    <div class="twic-item landscape">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item square">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item portrait">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item contain left">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item contain right">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item lg">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item md">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item sm">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
    <div class="cover square">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
  </main>
</template>

<script>
  export default {
    name: 'App',
  }
</script>

<style>
  .landscape {
    --twic-ratio: calc(4 / 3);
  }
  .portrait {
    --twic-ratio: calc(3 / 4);
  }
  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>
Edit TwicPics x Nuxt 3 - Style Driven

Responsive Example

Setting up components using CSS and CSS variables enables hassle-free responsive designs.

<your-page-or-component>.vue

<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
  </main>
</template>

<script>
  export default {
    name: 'App',
  }
</script>

<style>
  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

Your template features a single component that will follow your CSS directives and behave responsively.

Edit TwicPics x Nuxt3 - Art Direction

Working with ratio="none"

Particularly useful when creating hero banner, you can specify the height of your image while respecting its natural aspect ratio and maintaining an optimised CLS.

<your-page-or-component>.vue

<template>
  <TwicImg src="path/to/your/image" class="hero-image" ratio="none"></TwicImg>
</template>

<script>
  export default {
    name: 'App',
  }
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height: 500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height: 300px;
      width: 100%;
    }
  }
</style>
Edit TwicPics x Nuxt3 - Hero Image

Components Properties

TwicImg

This component can be used in place of an img element.

<TwicImg
  src="<path>"
  (mandatory)
  alt="<string>"
  ratio="<ratio>"
  mode="<contain|cover>"
  focus="<auto|coordinates>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<string>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  step="<integer>"
/>
AttributeDescriptionTypeDefault
altalt attribute contentStringbased on src
focusOnly useful in cover mode. Can be auto or coordinates. See the TwicPics focus attribute documentation for more information.String
modeCan be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain).Stringcover
placeholderCan be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. Setting will be overridden to none when using zoom transition.Stringpreview
positionOnly useful in contain mode. Locates the image inside the area. Syntax is the same as for CSS position properties like background-position or object-position. Useful values are top, bottom, left, right, left top, left bottom and so on.Stringcenter
preTransformA slash-separated list of TwicPics API transformations to be performed before resizing the image (see the TwicPics Manipulation documentation). If focus is supplied, it is applied first. Be aware that using this option can lead to unexpected results so use with caution!String
ratioA unitless width/height value pair (as in 4/3) that defines the aspect ratio of the display area. If height is not specified, it is assumed to be 1. A square area will be created by default. When set to none, ratio is determined based on width and height as computed by the browser in respect with CSS definitions. The --twic-ratio CSS variable is ignored in this instance. You are responsible for properly sizing the component when ratio="none".String1
srcPath to the image. When not provided, a red lightweight svg placeholder that displays its intrinsic dimensions is displayed in place of the absent image. When env is set to offline, that red lightweight svg is replaced by a simple red placeholder.String
stepSee the TwicPics step attribute documentation for more information.Integer10
transitionDetermines how image will be revealed once loaded. With a fade in effect (fade), a zoom effect (zoom), both (fade zoom) or without any transition (none). Unsupported values are handled as fade.Stringfade
transitionDurationDuration of the transition effect.String400ms
transitionTimingFunctionCSS timing function applied to the transition effect.Stringease
transitionDelayTransition delay of the transition effect.String0ms

TwicVideo

This component can be used in place of a video element.

<TwicVideo
  src="<path>"
  (mandatory)
  ratio="<ratio>"
  mode="<contain|cover>"
  focus="<auto|coordinates>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<string>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  step="<integer>"
/>
AttributeDescriptionTypeDefault
focusOnly useful in cover mode. Can be auto or coordinates. See the TwicPics focus attribute documentation for more information.String
modeCan be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain).Stringcover
placeholderCan be preview, meancolor, maincolor or none. See the TwicPics output transformation documentation for more information. Setting will be overridden to none when using zoom transition.Stringpreview
positionOnly useful in contain mode. Locates the image inside the area. Syntax is the same as for CSS position properties like background-position or object-position. Useful values are top, bottom, left, right, left top, left bottom and so on.Stringcenter
preTransformA slash-separated list of TwicPics API transformations to be performed before resizing the video (see the TwicPics Manipulation documentation). If focus is supplied, it is applied first. Be aware that using this option can lead to unexpected results so use with caution!String
ratioA unitless width/height value pair (as in 4/3) that defines the aspect ratio of the display area. If height is not specified, it is assumed to be 1. A square area will be created by default. When set to none, ratio is determined based on width and height as computed by the browser in respect with CSS definitions. The --twic-ratio CSS variable is ignored in this instance. You are responsible for properly sizing the component when ratio="none".String1
srcPath to the image. When not provided, a red lightweight svg placeholder that displays its intrinsic dimensions is displayed in place of the absent image. When env is set to offline, that red lightweight svg is replaced by a simple red placeholder.String
stepSee the TwicPics step attribute documentation for more information.Integer10
transitionDetermines how video will be revealed once loaded. With a fade in effect (fade), a zoom effect (zoom), both (fade+zoom) or without any transition (none). Unsupported values are handled as fade.Stringfade
transitionDelayTransition delay of the transition effect.String0ms
transitionDurationDuration of the transition effect.String400ms
transitionTimingFunctionCSS timing function applied to the transition effect.Stringease

CSS Variables

List of variables that can be used to configure your components using pure CSS.

<selector > {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function: <string>;
}

Each CSS variable corresponds to one of the components attributes listed in the Components Properties section. If present, the attribute takes precedence over the corresponding CSS variable.

VariableDescriptionHTML AttributeDefault
--twic-modeCan be contain or cover and determines if the image fills the area and is cropped accordingly (cover) or if the image will sit inside the area with no cropping (contain).modecover
--twic-positionOnly useful in contain mode. Locates the image inside the area. Syntax is the same as for CSS position properties like background-position or object-position. Useful values are top, bottom, left, right, left top, left bottom and so on.positioncenter
--twic-ratioFloating point value corresponding to a unitless width/height ratio (as in calc(4/3) or 1.333). Ratio will correspond to a square area by default.ratio1
--twic-transition-delayTransition delay of the transition effect.transitionDelay0ms
--twic-transition-durationDuration of the transition effect.transitionDuration400ms
--twic-transition-timing-functionCSS timing function applied to the transition effect.transitionTimingFunctionease

Questions and feedback

Fell free to submit an issue or to ask us anything by dropping a message in the chat.

responsive images

The All-In-One Toolbox For Your Images

The simplest, most powerful way to tackle responsive images