Cloudinary Image component for Next.js

Overview

     

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'
  }]}
/>
Comments
  • Update cropping.js

    Update cropping.js

    Description

    Fixes the Gravity issue while cropping image.


    Issue Ticket Number

    Fixes #29


    Type of change

    • [X] Bug fix (non-breaking change which fixes an issue)
    • [ ] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] This change requires a documentation update

    Checklist:

    • [X] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [X] I have created an issue ticket for this PR
    • [X] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [X] I have performed a self-review of my own code
    • [X] I have run tests locally to ensure they all pass
    • [X] I have commented my code, particularly in hard-to-understand areas
    • [X] I have made corresponding changes needed to the documentation
    opened by Smartmind12 25
  • Fix

    Fix "gravity" is read-only

    Description

    Fix "gravity" is read-only

    Issue Ticket Number

    Fixes [Issue #29 ]


    Type of change

    • [x] Bug fix (non-breaking change which fixes an issue)
    • [ ] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] This change requires a documentation update

    Checklist:

    • [x] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [x] I have created an issue ticket for this PR
    • [x] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [x] I have performed a self-review of my own code
    • [x] I have run tests locally to ensure they all pass
    • [x] I have commented my code, particularly in hard-to-understand areas
    • [x] I have made corresponding changes needed to the documentation
    released 
    opened by codingis4noobs2 18
  • Upload widget component

    Upload widget component

    Description

    I created the Upload Widget based on the examples given at

    • https://github.com/colbyfayock/cloudinary-examples/tree/main/examples/nextjs-upload-widget-signed
    • https://github.com/colbyfayock/cloudinary-examples/tree/main/examples/nextjs-upload-widget-preset

    I also added an Upload Button to further abstract the Upload Widget for ease of use for users.

    This is the first draft @colbyfayock, please could you help me take a look to ensure I'm in the right direction? Also apologies for my formatting from my prettier that changed some js and CSS files

    Bugs left to fix:

    • [x] only one widget gets triggered, if multiple widgets are rendered on one page
    • [x] better error update on signed widgets
    • [ ] revert formatting

    Issue Ticket Number

    Fixes [Issue #4 ]


    Type of change

    • [ ] Bug fix (non-breaking change which fixes an issue)
    • [ ] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] This change requires a documentation update

    Checklist:

    • [x] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [x] I have created an issue ticket for this PR
    • [x] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [x] I have performed a self-review of my own code
    • [ ] I have run tests locally to ensure they all pass
    • [x] I have commented my code, particularly in hard-to-understand areas
    • [ ] I have made corresponding changes needed to the documentation
    released 
    opened by agbanusi 15
  • Implement error polling for image processing with timeout

    Implement error polling for image processing with timeout

    Description

    Implements image polling on the client side so that when using transformations which require processing and return a 423 status code, the image loads upon completion. This intends to use the onError function available for all next/image components. For polling, the general approach is that when an error occurs, a simple fetch is made to the image URL. We will check the response and then continue polling until it's available if it's a 423 status code.

    Issue Ticket Number

    Fixes #1

    Type of change

    • [ ] Bug fix (non-breaking change which fixes an issue)
    • [x] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] Fix or improve the documentation
    • [ ] This change requires a documentation update

    Checklist

    • [ ] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [ ] I have created an issue ticket for this PR
    • [ ] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [ ] I have performed a self-review of my own code
    • [ ] I have run tests locally to ensure they all pass
    • [ ] I have commented my code, particularly in hard-to-understand areas
    • [ ] I have made corresponding changes needed to the documentation
    released 
    opened by michizhou 12
  • Apply transformations from the Cloudiary URL

    Apply transformations from the Cloudiary URL

    TLDR;

    As discussed in #2 the Cloudiary URL may contain transformations that apply to the image. We would like to be able to apply the modification present in the url to the image component.

    Situation

    The Cloudiary URL may have transformations in it, that are applied to the image it links to. The logic to be able to handle a Cloudiary URL in the CldImage component is being implemented in #8. But as discussed in #2 it would be too complex for this first implementation to handle these transformations.

    An url with transformations applied to it looks like the following:

    https://res.cloudinary.com/colbycloud-next-cloudinary/image/upload/w_100,h_100/v1/images/turtle
    

    And returns an image like this: transformed image

    While a url without transformation looks like this:

    https://res.cloudinary.com/colbycloud-next-cloudinary/image/upload/v1/images/turtle
    

    And returns an image like this: normal image

    Implementation

    The goal would be able to parse the url and retrieve the transformation part w_100,h_100, then parse this string into the component transformations and apply them. A possible extra feature, to avoid overriding transformations would be to have a useUrlTransformations prop in the component that would let us know which transformations to use, the ones in the url or the ones in the props of the component

    enhancement help wanted released 
    opened by danielolaviobr 12
  • [docs]: implement recommended community standards

    [docs]: implement recommended community standards

    Adds the recommended GitHub community standards to make the project contributor friendly.

    fixes #10

    You can review these suggestions and maybe add some preferences and I will add them to the files.

    released 
    opened by orama254 9
  • Support full Cloudinary URLs as the `src` prop

    Support full Cloudinary URLs as the `src` prop

    To make it easier for people to use, support grabbing the public ID from the src prop.

    Example:

    <CldImage src="https://res.cloudinary.com/colbycloud-next-cloudinary/image/upload/images/turtle" />
    
    help wanted 
    opened by colbyfayock 9
  • Extract transformations and effect in url construct

    Extract transformations and effect in url construct

    Description

    Used the regex to extract the URL transformations and add to the cloudinaryUrlConstructor with the permission of the new useUrlTransformations property

    Issue Ticket Number

    Fixes #9

    Type of change

    • added a new property for allowing user to make a choice to use URL transformation
    • extract transformations from URL using regex
    • ran changes correctly
    • test
    • [ ] Bug fix (non-breaking change which fixes an issue)
    • [x] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] Fix or improve the documentation
    • [ ] This change requires a documentation update

    Checklist

    • [x] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [x] I have created an issue ticket for this PR
    • [ ] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [x] I have performed a self-review of my own code
    • [x] I have run tests locally to ensure they all pass
    • [x] I have commented my code, particularly in hard-to-understand areas
    • [ ] I have made corresponding changes needed to the documentation
    released 
    opened by agbanusi 8
  • Support full Cloudinary URLs as the `src` prop

    Support full Cloudinary URLs as the `src` prop

    Issue #2

    This PR enables the src prop to receive the image cloudiary url. It only retrieves the public id from the url and passes it forward. It passes the version as well, if it is present in the url.

    This PR does not solves the transformation case discussed in #9

    released 
    opened by danielolaviobr 8
  • Implement initial polling for image processing

    Implement initial polling for image processing

    Description

    Implements image polling on the client side so that when using transformations which require processing and return a 423 status code, the image loads upon completion. This intends to use the onError function available for next/future/image components. For polling, the general approach is that when an error occurs, a simple fetch is made to the image URL. We will check the response and then continue polling until it's available if it's a 423 status code.

    Issue Ticket Number

    Fixes #1

    Type of change

    • [ ] Bug fix (non-breaking change which fixes an issue)
    • [x] New feature (non-breaking change which adds functionality)
    • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
    • [ ] Fix or improve the documentation
    • [ ] This change requires a documentation update

    Checklist

    • [ ] I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
    • [ ] I have created an issue ticket for this PR
    • [ ] I have checked to ensure there aren't other open Pull Requests for the same update/change?
    • [ ] I have performed a self-review of my own code
    • [ ] I have run tests locally to ensure they all pass
    • [ ] I have commented my code, particularly in hard-to-understand areas
    • [ ] I have made corresponding changes needed to the documentation
    opened by michizhou 7
  • Add UploadWidget component that works out of the box with Next.js

    Add UploadWidget component that works out of the box with Next.js

    Cloudinary offers an Upload widget that works by adding a script tag to the page.

    We can make the Next.js-ready by building a component around it.

    Here is how we can approach this:

    • https://github.com/colbyfayock/cloudinary-examples/tree/main/examples/nextjs-upload-widget-signed
    • https://github.com/colbyfayock/cloudinary-examples/tree/main/examples/nextjs-upload-widget-preset
    help wanted 
    opened by colbyfayock 7
  • [Feature] Screen, Multiply, and Other Layer Effects

    [Feature] Screen, Multiply, and Other Layer Effects

    Feature Request

    Is your feature request related to a problem? Please describe.

    multiply
    screen
    

    Describe the solution you'd like

    Describe alternatives you've considered

    Additional context

    opened by colbyfayock 1
  • [Bug] Preserve Transformations doesn't work

    [Bug] Preserve Transformations doesn't work

    Bug Report

    Describe the bug

    image

    example URL

    https://res.cloudinary.com/colbycloud-next-cloudinary/image/upload/c_limit,w_960/f_auto/q_auto/v1/images/c_fill%252Ch_300%252Cw_250/e_blur:300/turtle
    

    Is this a regression?

    Steps To Reproduce the error

    Expected behaviour

    CodeSandbox or Live Example of Bug

    Screenshot or Video Recording

    Your environment

    • OS:
    • Node version:
    • Npm version:
    • Browser name and version:

    Additional context

    opened by colbyfayock 0
  • [Feature] Nested Overlays

    [Feature] Nested Overlays

    Feature Request

    Is your feature request related to a problem? Please describe.

    Cloudinary gives you the ability to "nest" overlays in a way that allows the elements to flow in a natural way.

    Example would be based on dynamic text positioning, the nested overlay would dynamically be placed after it if using relative positioning.

    Describe the solution you'd like

    Not quite sure, thinking maybe along the lines of:

    overlays={[
      {
        ...
        children: [{ ...overlays }]
    ]}
    

    Where the children would be instances of overlays, so the overlays plugin would just recursively parse the children and down

    Describe alternatives you've considered

    maybe childOverlays instead?

    opened by colbyfayock 1
  • Typescript Support

    Typescript Support

    Feature Request

    Basic typings for the ClgImage component and more.

    Is your feature request related to a problem? Please describe.

    Describe the solution you'd like

    Begin moving the project to a Typescript-first experience. This will get harder as the project gets bigger. Happy to help with this transition!

    Having prop typings for components is pretty much essential for libraries at this point, as they provide inline documentation.

    opened by cobbvanth 8
  • [Bug] Blurred placeholder's aren't showing

    [Bug] Blurred placeholder's aren't showing

    Bug Report

    Describe the bug

    The placeholder doesn't appear on the image background, this also happens on the examples page here - https://next-cloudinary.spacejelly.dev/components/cldimage/examples

    Seems like from the next js docs it needs to be a base64 encoded image instead of a url

    Is this a regression?

    Not sure

    Steps To Reproduce the error

    1. Add a CldImage component
    2. Set the placeholder="blur" option
    3. Delete the src and srcset attributes on inspect to view the unloaded image
    4. See there's no placeholder image showing

    Expected behaviour

    The image should show a blurred placeholder

    Screenshot or Video Recording

    image

    opened by ThusStyles 6
Releases(v1.6.0)
Owner
Colby Fayock
Destructuring React & the Static Web
Colby Fayock
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
optimize image & upload file to cloud as image bed with tiny image automic.

Rush! 图片压缩 & 直传图床工具 这是一个兴趣使然的项目, 希望 Rush! 能让这个世界的网络资源浪费减少一点点 下载 Downloads 获取最新发行版 功能 Features 拖拽批量压缩图片, 支持格式 jpg/png/gif Drop to optimize, jpg/png/gif

{ Chao } 3 Nov 12, 2022
A Javascript library that discourages and prevents image theft/download by preventing client ability to retrieve the image.

ProtectImage.js ProtectImage.js is a Javascript library that helps prevent image theft by disabling traditional user interactions to download/copy ima

null 4 Aug 18, 2022
Simple JavaScript Library to add parallax image to background-image

Backpax Simple JavaScript Library to add parallax image to background-image Install $ npm install backpax --save Demo Demo page is here Usage If you

appleple 13 Oct 12, 2022
Piccloud is a full-stack (Angular & Spring Boot) online image clipboard that lets you share images over the internet by generating a unique URL. Others can access the image via this URL.

Piccloud Piccloud is a full-stack application built with Angular & Spring Boot. It is an online image clipboard that lets you share images over the in

Olayinka Atobiloye 3 Dec 15, 2022
Hashmat Noorani 4 Mar 21, 2023
🖼️ An image select component for Streamlit

streamlit-image-select ??️ An image select component for Streamlit. This custom component works just like st.selectbox but with images. It's a great o

Johannes Rieke 28 Jan 3, 2023
This simple project, show how work with async Fetch, function component and class component

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

DaliyaAsel 2 Feb 17, 2022
dynamic-component-app is an angular application for dynamic component template creation

MyApp This project was generated with Angular CLI version 14.1.0. Development server Run ng serve for a dev server. Navigate to http://localhost:4200/

Aniket Muruskar 7 Aug 26, 2022
next-graphql-server is a library for building production-grade GraphQL servers using Next.js with API Routes

next-graphql-server next-graphql-server is an easy to use Next.js library for creating performant GraphQL endpoints on top of Next.js API Routes. Star

Jakub Neander 82 Nov 21, 2022
💻 A simple Create Next App template to start your projects with Next.js, TypeScript, ESLint, Prettier and other tools.

⚡ Next Typescript Template ⚡ A simple Create Next App template to start your projects with Next.js, TypeScript, ESLint, Prettier and other tools. Quic

João Gabriel 13 Nov 23, 2022
A fullstack next.js template with all the fun stuff like next auth, mongodb, prisma, chakra ui

Welcome to FullStack Next.js template ?? A fullstack next.js template with all the fun stuff like next auth, mongodb, prisma, chakra ui ✨ Demo Tech Ne

Avneesh Agarwal 10 Oct 16, 2022
This is a Next.js project bootstrapped with create-next-app.

Getting Started First, run the development server: npm run dev # or yarn dev Open http://localhost:3000 with your browser to see the result. You can s

J.D. 8 Dec 5, 2022
Change the color of an image to a specific color you have in mind.

image-recolor Run it: https://image-recolor.vercel.app/ image.recolor.mov Acknowledgments Daniel Büchele for the algorithm: https://twitter.com/daniel

Christopher Chedeau 21 Oct 25, 2022
A refined tool for exploring open-source projects on GitHub with a file tree, rich Markdown and image previews, multi-pane multi-tab layouts and first-class support for Ink syntax highlighting.

Ink codebase browser, "Kin" ?? The Ink codebase browser is a tool to explore open-source code on GitHub, especially my side projects written in the In

Linus Lee 20 Oct 30, 2022