https://github.com/jaychase/ngx-picture
Properly sized images in next generation formats for Angular
https://github.com/jaychase/ngx-picture
angular cloudinary defer-loading imagekit lighthouse responsive-images webp
Last synced: 26 days ago
JSON representation
Properly sized images in next generation formats for Angular
- Host: GitHub
- URL: https://github.com/jaychase/ngx-picture
- Owner: JayChase
- License: mit
- Created: 2019-10-15T23:57:14.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T10:44:55.000Z (about 3 years ago)
- Last Synced: 2025-03-31T05:32:49.286Z (about 1 year ago)
- Topics: angular, cloudinary, defer-loading, imagekit, lighthouse, responsive-images, webp
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ngx-picture
- Size: 4.59 MB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: license.md
Awesome Lists containing this project
README
# ngx-picture
An Angular library to help properly size, lazy load images, and use next generation formats.
Help improve app performance and fix common [Lighthouse](https://developers.google.com/web/tools/lighthouse) opportunities:
- **Serve images in next-gen formats**
- **Properly size images**
- **Defer offscreen images**
Ready made configurations available for:
- [Cloudinary](https://cloudinary.com/)
- [imagekit.io](https://imagekit.io/)
- [GraphCMS](https://graphcms.com/)
For live demos:
- [Storybook](https://jaychase.github.io/ngx-picture)
- [StackBlitz](https://stackblitz.com/edit/ngx-picture-blitz)
- [npm](https://www.npmjs.com/package/ngx-picture)
## Install
Angular 9+
```bash
npm i --save ngx-picture@latest
```
Angular < 9
```bash
npm i --save ngx-picture@2.0.4
```
## Configure
Import **NgxPictureModule** into **app.module.ts** and call **forRoot** suppyling the config.
```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import {
DEFAULT_BREAKPOINTS,
ImageFormat,
NgxPictureModule
} from 'ngx-picture';
import { AppComponent } from './app.component';
// 1: supply a function to create the srcset urls for each breakpoint
export function srcInterpolator(
url: string,
imageFormat: ImageFormat,
breakpoint: string,
breakpointValue: number
) {
return `${url.split('.')[0]}-${breakpointValue}.${
imageFormat === 'jpeg' ? 'jpg' : 'webp'
}`;
}
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
,
NgxPictureModule.forRoot({
breakpoints: DEFAULT_BREAKPOINTS, //2. the break points to create sources for
imageFormats: ['webp', 'jpeg'], //3. the image formats to create sources for. *
srcInterpolator
})
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {}
```
\* Image formats must be in order of precedence. In this example if **webp** s supported it will be used.
### Using the bundled configurations (Cloudinary, ImageKit and GraphCMS)
```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgxPictureModule, CLOUDINARY_CONFIG } from 'ngx-picture';
import { AppComponent } from './app.component';
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, NgxPictureModule.forRoot(CLOUDINARY_CONFIG)],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {}
```
## Using the ngx-picture component
```html
```
If **lazyLoad** is true the component will use an [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) (if it is supported by the browser) to only render the picture element if the component is in view.
\*Remember to import the **NgxPictureModule** into the relevant module.
## Advanced configuration
### Changing the breakpoint value type and srcInterpolator
**NgxPictureConfig** is generic so you can change the brreakpoint values to anything required in the **srcInterPolator** function. This example is using the [Angular CDK](https://material.angular.io/cdk/layout/overview) breakpoints for the breakpoint keys.
```typescript
import { Breakpoints } from '@angular/cdk/layout';
export interface Dimensions {
h: number;
w: number;
}
const ngxPictureConfig: NgxPictureConfig = {
breakpoints: {
[Breakpoints.XSmall]: { h: 10, w: 10 },
[Breakpoints.Medium]: { h: 100, w: 100 },
[Breakpoints.Large]: { h: 200, w: 200 }
},
imageFormats: ['webp', 'jpg'],
srcInterpolator: (
url: string,
imageFormat: ImageFormat,
breakpoint: string,
breakpointValue: Dimensions
) => `${url}/w:${breakpointValue.w}/h:${breakpointValue.h}`
};
export function srcInterpolator(
url: string,
imageFormat: ImageFormat,
breakpoint: string,
breakpointValue: number
) {
return `${url.split('.')[0]}-${breakpointValue}.${
imageFormat === 'jpeg' ? 'jpg' : 'webp'
}`;
}
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule.withServerTransition({ appId: 'serverApp' }),
BrowserAnimationsModule,
MatButtonModule,
MatCardModule,
MatListModule,
NgxPictureModule.forRoot(ngxPictureConfig)
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {}
```
### Changing the image template
To use a custom img element provide an **ngTemplate** called **#imgTemplate**.
```html
![]()
```
The data context for the template is:
```typescript
{
src: string,
alt: string
}
```
## Example of rendered element
```html
```
## Styling
The **picture** element in the component has the class **ngx-picture\_\_picture** and the img element has the class **ngx-picture**picture**img**.
```scss
.your-picture-class {
.ngx-picture__picture {
width: 100%;
.ngx-picture__picture__img {
width: 100%;
}
}
}
```
## More
To clone this repo and run it locally.
```bash
git clone https://github.com/JayChase/ngx-picture.git
cd ngx-picture
npm i
npm run build
```
### Demo
```bash
ng s
```
### Storybook
```bash
npm run storybook
```