Gatsby Theme Cloudinary Gallery is a Gatsby theme that adds a Cloudinary-hosted image gallery to any Gatsby site, using your Cloudinary API credentials to fetch and display images.
What is Gatsby Theme Cloudinary Gallery?
Gatsby Theme Cloudinary Gallery is a Gatsby theme (an npm packagable plugin) that creates an image gallery from your Cloudinary account and embeds it into a Gatsby site. It takes your Cloudinary cloud name, API key, and API secret as required options, fetches image metadata per the configured type, prefix, and maxResults, and outputs both a gallery page and a reusable Gallery component. The theme is built with Gatsby, styled with Tailwind CSS, and renders images through the Cloudinary React SDK, which applies transformations on the fly.
Key Features
- Simple installation — Install with
npm install gatsby-theme-cloudinary-gallery, then add it to the plugins array in gatsby-config.js with your Cloudinary credentials.
- Cloudinary integration — Required options are cloudName, apiKey, and apiSecret from the Cloudinary console; the README recommends loading them into environment variables using dotenv to avoid committing secrets.
- Flexible fetching — The type option accepts upload, private, authenticated, facebook, twitter, gplus, instagram_name, gravatar, youtube, hulu, vimeo, animoto, or dailymotion; maxResults defaults to 10 and can be raised to 500; prefix filters resources by public ID.
- Automatic transformations — Every image is rendered with the Cloudinary React SDK's Image and Transformation components using defaults of fetchFormat auto, width 800, height 800, lazy loading, radius 20, gravity face, and crop fill.
- Reusable Gallery component — The exported Gallery component can be imported into any page, giving you an embeddable gallery beyond the default page created at the basePath.
- Gatsby shadowing — You can override theme components by creating files such as src/gatsby-theme-cloudinary-gallery/components/Heading.js; the demo replaces the heading with "Cute Puppies Gallery".
- Live demo and deployment — A demo app is linked, and a one-click "Deploy with Vercel" button sets up the demo repository with your Cloudinary environment variables.
Who should use Gatsby Theme Cloudinary Gallery?
- Gatsby developers building a portfolio or content site who want a gallery without hand-coding a Cloudinary API integration.
- Photographers and visual creators who already store images in Cloudinary and need a responsive, lazy-loaded gallery with face-aware cropping.
- Teams and agencies that use Cloudinary for asset management and want a gallery that can be styled through Gatsby's shadowing API for client work.
What can you do with Gatsby Theme Cloudinary Gallery?
- Embed a gallery in any page — Import the Gallery component and drop it into your homepage, a dedicated gallery page, or anywhere else; the theme also creates a page at the configurable basePath (default /).
- Control which images are displayed — Set the type to something like instagram_name or youtube to show non-upload assets, or use a prefix to show only images whose public ID starts with a certain string.
- Customize the gallery appearance — Use Gatsby shadowing to swap out the Heading or Gallery components with your own JSX and Tailwind utility classes, as shown in the demo.
- Deploy a working gallery instantly — Use the Vercel deployment button, which clones the demo, sets up environment variables for CLOUDNAME, APIKEY, and APISECRET, and publishes a live gallery.
How does Gatsby Theme Cloudinary Gallery work?
Once installed and configured with your Cloudinary credentials, the theme uses the Cloudinary API during the Gatsby build to fetch image resources matching your options. It then generates a gallery page and exposes a Gallery component that renders the images responsively. The Cloudinary React SDK's Image and Transformation components handle delivery, with default transformations applied so images are lazy-loaded, resized to 800x800, face-cropped, and rounded.
Pros and cons
- Pros: Minimal setup with one npm package and a handful of configuration options; uses Cloudinary's built-in face detection and format optimization; fully customizable through Gatsby shadowing; includes a runnable demo and one-click Vercel deployment.
- Cons: A Cloudinary account and API credentials are mandatory, and the default maxResults is 10, so you need to raise it to show more images at once.
Alternatives
- Gatsby Theme Gallery — an older Gatsby gallery theme that inspired this one.
- gatsby-source-cloudinary — a Gatsby source plugin that pulls Cloudinary assets into Gatsby's GraphQL data layer, also cited as inspiration.
FAQ
What do I need to use gatsby-theme-cloudinary-gallery?
You need a Gatsby project, a Cloudinary account, and your cloud name, API key, and API secret from the Cloudinary console. These three values are required in the theme options, and the README recommends storing them in a .env file with dotenv so they are not committed to version control.
What options can I pass to the theme?
The required options are cloudName, apiKey, and apiSecret. Optional options are basePath (URL for the gallery page, default /), type (asset storage type, default upload), maxResults (maximum assets to return, default 10, cap 500), and prefix (filter by public ID prefix). All are passed in gatsby-config.js.
Can I change how the gallery looks?
Yes. Gatsby's shadowing API lets you replace the theme's components by creating files in your site under src/gatsby-theme-cloudinary-gallery/. For example, to change the gallery heading, add src/gatsby-theme-cloudinary-gallery/components/Heading.js; the demo shows changing the title to "Cute Puppies Gallery".
It applies transformations through Cloudinary by default. The Transformation component is set to fetchFormat auto, width 800, height 800, loading lazy, radius 20, gravity face, and crop fill. Because the Gallery component can be shadowed, you can adjust these defaults.
Is there a live demo?
Yes. The README links to a live demo at https://gatsby-theme-cloudinary-gallery.vercel.app and provides a Deploy with Vercel button that sets up the demo repo with your Cloudinary environment variables.
