kbravh / next-cloudinary

Cloudinary Image component for Next.js

     

Cloudinary Next.js Component

Get the best of Cloudinary in Next.js with the CldImage component!

🚨 EXPERIMENTAL: while this should be working pretty well, it's consider experimental, so use at your own risk!

This plugin is not officially supported by Cloudinary.

⚡️ Getting Started

Installation

• Install next-cloudinary with:

yarn add next-cloudinary
# or
npm install next-cloudinary

• Add an environment variable with your Cloud Name:

NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

• Import the CldImage component:

import { CldImage } from 'next-cloudinary';

Usage

The basic required props include width, height, and src:

<CldImage
  width="600"
  height="600"
  src="<Public ID>"
/>

You can further take advantage of Cloudinary features like background removal and overlays by adding additional props:

<CldImage
  width="600"
  height="600"
  src="<Public ID>"
  crop="thumb"
  gravity="faces"
  removeBackground
  tint="100:blue:green:red"
  underlays={[{
    publicId: '<Public ID>',
    width: 600,
    height: 600,
    crop: 'fill'
  }]}
/>

As CldImage is a wrapper around the Next.js Image component, all built-in Image component features will work out-of-the-box including the layout prop.

🛠 Configuration

General Props

Prop Name	Type	Example
crop	string	"thumb"
gravity	string	"faces"
overlays	array	See Below
removeBackground	bool/string	true
underlays	array	See Below
zoompan	bool/string/object	See Below

Effect Props

Prop Name	Type	Example
art	string	"al_dente"
autoBrightness	bool/string	true, "80"
autoColor	bool/string	true, "80"
autoContrast	bool/string	true, "80"
assistColorblind	bool/string	true, "20", "xray"
blackwhite	bool/string	true, "40"
blur	bool/string	true, "800"
blurFaces	bool/string	true, "800"
blurRegion	bool/string	true, "1000,h_425,w_550,x_600,y_400"
brightness	bool/string	true, "100"
brightnessHSB	bool/string	true, "100"
cartoonify	bool/string	true, "70:80"
colorize	string	"35,co_darkviolet"
contrast	bool/string	true, "100", "level_-70"
distort	string	"150:340:1500:10:1500:1550:50:1000", "arc:180.0"
fillLight	bool/string	true, "70:20"
gamma	bool/string	true, "100"
gradientFade	bool/string	true, "symmetric:10,x_0.2,y_0.4"
grayscale	bool	true
improve	bool/string	true, "50", "indoor"
negate	bool	true
oilPaint	bool/string	true, "40"
outline	bool/string	true, "40", "outer:15:200"
pixelate	bool/string	true, "20"
pixelateFaces	bool/string	true, "20"
pixelateRegion	bool/string	true, "35,h_425,w_550,x_600,y_400"
redeye	bool/string	true
replaceColor	string	"saddlebrown", "2F4F4F:20", "silver:55:89b8ed"
saturation	bool/string	true, "70"
sepia	bool/string	true, "50"
shadow	bool/string	true, "50,x_-15,y_15"
sharpen	bool/string	true, "100"
shear	string	"20.0:0.0"
simulateColorblind	bool/string	"deuteranopia"
tint	bool/string	true, "100:red:blue:yellow"
unsharpMask	bool/string	true, "500"
vectorize	bool/string	true, "3:0.5"
vibrance	bool/string	true, "70"
vignette	bool/string	true, "30"

View the Cloudinary docs to see learn more about using effects.

Background Removal

Removing backgrounds require enabling the Cloudinary AI Background Removal Add-On which includes a free tier for getting started.

Once enabled, you can simply apply the removeBackground parameter.

Example:

<CldImage
  ...
  removeBackground
/>

Overlays

The overlays prop is an array of objects with the following configuration options:

Property Name	Type	Example
effects	array	See Below
position	object	See Below
publicId	string	"thumb"
text	object	See Below

The position property can include:

Property Name	Type	Example
angle	number	45
gravity	string	'"north_west"'
x	number	10
y	number	10

Objects in the effects array can include:

Property Name	Type	Example
aspectRatio	string	"3.0"
crop	string	10
gravity	string	'"north_west"'
height	number	'600'
width	number	'600'

The text property can include:

Property Name	Type	Example
color	string	"blueviolet"
fontFamily	string	"Open Sans"
fontSize	number	48
fontWeight	string	"bold"
letterSpacing	number	"14"
textDecoration	string	"underline"

Adding Images

You can add images on top of other images by using image-based overlays.

Example:

<CldImage
  ...
  overlays={[{
    publicId: '<Public ID>',
    position: {
      x: 10,
      y: 10,
      gravity: 'north_west',
    },
    effects: [
      {
        crop: 'fill',
        gravity: 'auto',
        width: 500,
        height: 500
      }
    ]
  }]}
/>

Adding Text

You can add text on top of your image with text-based overlays.

Example:

<CldImage
  ...
  overlays={[{
    width: 2670 - 20,
    crop: 'fit',
    position: {
      x: 10,
      y: 10,
      gravity: 'north_west',
    },
    text: {
      color: 'blueviolet',
      fontFamily: 'Source Sans Pro',
      fontSize: 120,
      fontWeight: 'bold',
      textDecoration: 'underline',
      letterSpacing: 14,
      text: 'Text'
    }
  }]}
/>

Underlays

Underlays function very similar to overlays in terms of options, however they do not support text.

See the examples above under Overlays to learn more about the available configurations.

Example:

<CldImage
  ...
  underlays={[{
    publicId: '<Public ID>',
    width: 1920,
    height: 1200,
    crop: 'fill'
  }]}
/>

Contributors

Colby Fayock 💻 📖 💡

Daniel Olavio 💻