Angular

angular-cover

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

TwicPics Components are available in Angular version 11 to 13.

You can find usage examples in our online demo project.

Edit TwicPics x Angular - Basic

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

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

Module declaration in app.module.ts

You need to import the TwicPicsComponentsModule within your app.module.ts file.

While importing angular components or module, you will have to select the targeted version.
// import TwicPicsComponentsModule
import { TwicPicsComponentsModule } from '@twicpics/components/angular11'

Add the import part

// import TwicPics Angular Module
import { TwicPicsComponentsModule } from '@twicpics/components/angular<your-targeted-version>'

and the usage declaration of the module

@NgModule( {
  "imports": [
    TwicPicsComponentsModule,
  ],
} )
// here is an example of a `app.module.ts` configured with TwicPics.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { AppComponent } from './app.component'
import { TwicPicsComponentsModule } from '@twicpics/components/angular13'

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, TwicPicsComponentsModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

TwicPics Components Configuration in app.component.ts

The configuration part (see Setup Options) is done in app.component.ts.

Here again, you will have to select the targeted version while importing angular components.
//here is an example of a `Angular` app.component.ts configured with TwicPics.
import { Component } from '@angular/core'
import { installTwicPics } from '@twicpics/components/angular13'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {}

// TwicPics Components configuration (see Setup Options)
installTwicPics({
  domain: 'https://<your-domain>.twic.pics',
  anticipation: 0.5,
  step: 100,
})

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 for use in the scope of the module into which you have imported TwicPicsComponentsModule see Module Declaration.

Just use them in your template files in place of img or video tags.

<your-component-within-app.module>.component.html

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

Basic usage

<your-component-within-app.module>.component.html

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

Style-Driven Approach

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

<your-component-within-app.module>.component.css

.landscape {
  --twic-ratio: calc(4 / 3);
}

.portrait {
  --twic-ratio: calc(3 / 4);
}

.square {
  --twic-ratio: calc(1);
}

.contain {
  --twic-mode: contain;
}

.cover {
  --twic-mode: cover;
}

.left {
  --twic-position: left;
}

.right {
  --twic-position: right;
}

.lg {
  width: 300px;
}

.md {
  width: 150px;
}

.sm {
  width: 100px;
}

<your-component-within-app.module>.component.html

<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="contain left">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
  <div class="contain right">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="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 className="cover square">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
</main>
Edit TwicPics x Angular - Style Driven

Responsive Example

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

<your-component-within-app.module>.component.css

.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);
  }
}

<your-component-within-app.module>.component.html

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

<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
Edit TwicPics x Angular - 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.

styles.css

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

@media (min-width: 1024px) {
  .hero-image {
    height: 300px;
    width: 100%;
  }
}

<your-page-or-component>.html

<TwicImg src="path/to/your/image" class="hero-image" ratio="none"></TwicImg>
Edit TwicPics x Angular - 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

Mode Type

Union type for all possible values on mode property.

type Mode = `contain` | `cover`

To dynamically set the mode property in TwicImg (or TwicVideo) component you must declare a variable of type Mode.

<your-component>.ts

import { Mode } from "@twicpics/components/angular13";

@Component({
  selector: ...,
  templateUrl: ...,
  styleUrls: ...,
})
export class YourComponent {
  yourModeVariable:Mode = `contain`;

}

<your-component>.html

<TwicImg src="path/to/your/image" [mode]="yourModeVariable"></TwicImg>

Placeholder Type

Union type for all possible values on placeholder property.

type Placeholder = `maincolor` | `meancolor` | `none` | `preview`

To dynamically set the mode property in TwicImg (or TwicVideo) component you must declare a variable of type Placeholder.

<your-component>.ts

import { Placeholder } from "@twicpics/components/angular13";

@Component({
  selector: ...,
  templateUrl: ...,
  styleUrls: ...,
})
export class YourComponent {
  yourPlaceholderVariable:Placeholder = `none`;

}

<your-component>.html

<TwicImg
  src="path/to/your/image"
  [placeholder]="yourPlaceholderVariable"
></TwicImg>

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