Cloudinary SDK for Svelte
Go to file
2023-05-22 22:08:47 +02:00
.github Create FUNDING.yml 2020-11-12 11:52:25 +01:00
src Set default crop option when using only height and width 2021-11-07 10:07:48 -06:00
.gitignore docs 2020-11-11 21:26:59 +01:00 docs, dependencies, readme 2021-12-26 21:56:15 +01:00
LICENSE Create LICENSE 2020-12-27 18:28:39 +01:00
package.json use pnpm 2021-12-26 21:56:57 +01:00
pnpm-lock.yaml docs, dependencies, readme 2021-12-26 21:56:15 +01:00 deprecation notice 2023-05-22 22:08:47 +02:00
tsconfig.json initial commit 2020-11-08 11:22:02 +01:00
vercel.json cleanurls 2020-11-11 21:29:02 +01:00



The npm package will be transfered to them.


dependencies downloads badge types badge version badge minzip size badge

This is a little library that aims at integrating and making it easier to use the svelte with Cloudinary. There is an official integration coming, but it's not ready and for not does not work great for now (SSR e.g.).

🌈 Features

  • Fully typed and typescript compatible
  • Tiny: ~30kb gzip (Of which 99% is the cloudinary dep.)
  • Automatic resizing based on the DOM and applied CSS
  • Automatic lazy loading
  • Fully compatible with native cloudinary options
  • Sapper (SSR) compatible

🗂 Docs

Questions & More -> Discussions

🚀 Quickstart

npm install svelte-cloudinary

  import { image, initialize } from 'svelte-cloudinary'

  initialize({ cloud_name: 'myCloudinaryCloud' })

  const src = 'my/cloudinary/asset'

  img {
    width: 50vw;
    height: 50vh;
    object-fit: cover;

  use:image={{ src, bind: true, lazy: true }}
  alt="background" />

This will formulate the Cloudinary url and insert it into the img.src property. Also it will resize to the img object itself because we set bind: true.

⚠️ In firefox if you want to use the bind option to automatically compute sizes you need to set img { display: inline-block or block; } otherwise there can be problems with getComputedStyle.

☁️ Cloudinary Setup

If you want the use super handfull auto upload function (which I think will apply to everyone) you have to set configure a few settings first.

  • Settings -> Security -> Allowed fetch domains: Add your domain(s) from which the images are fetched from.
  • Settings -> Upload -> Auto upload mapping: Set the mapping for your domain and/or path

Immagine you want to serve an image with the url of:

  1. Settings -> Security -> Allowed fetch domains: Add to the list.
  2. Settings -> Upload -> Auto upload mapping:
    Folder: myimages
    URL prefix:

Now you can use the auto upload funtion like this:

  use:image={{ src: 'myimages/elephants.png' }}
  alt="background" />

🤔 Why an action and not component?

Well components are great of course, but when we only need to set a src tags we can leverage the upsides of a svelte action

What are benefits?

  • Native styling (Svelte for now does not allow easy styling of child components)
    With an action we can easily use local styling beacuse we still have access to the <img /> element
  • Lightweight
  • Reusable and composable


  • The src will not be set serverside, so also not in the initial server response. Which I believe is not that bad though for images.

👷 Sapper

If you are using sapper you can initialize it once in your root _layout.svelte.

<script lang="ts">
	import { initialize } from 'svelte-cloudinary'

	initialize({ cloud_name: 'mycloud' })

  // ...

🤓 Key Concepts


default true

If images should use the Intersection Observer API to lazy load.


default 200

The step property helps reducing the amounts of transformations cloudinary need to perform and less credits being billed to you.

How? Basically whenever we calculate the dynamic size of the image rendered on the DOM we will get very specific numbers depending on the device.

With step we approximate the size needed to the nearset bigger multiple of step.


Imagine the same <img /> has the width of 420,470 and 1080 on an iPhone, Android and Laptop respectively.

With a step size of e.g. 100 (<img use:image={{ ..., step: 100 }} />) they will become 500, 500, and 1100. This will limit the ammount of transformations needed.


With bind we can dynamically set the width and/or height of the transformed image depending of the rendered size.

  • bind: this The size of the <img /> element
  • bind: el The computed size of another element in the dom (useful for a carousel e.g.)
  • bind: { width: this } Only bind the width, leaving the height free. Also works with height of course
  • bind: { width: '.wrapper' } Finds the closest element that matches the selector and uses it for width.

If you provide a bind options (<img use:image={{..., bind: true }} />) but no crop option, we will automatically add crop: 'fill' otherwise the image will not be resized by cloudinary.

<img use:image={{ src, bind: true }} />
<!-- Is internally equivalent to the following -->
<img use:image={{ src, bind: true, options: { crop: 'fill' } }} />

⌨️ Examples

Fixed size

  use:image={{ src, options: { width: 200, height: 100, crop: 'fill' } }}


<!-- Simple -->
  use:image={{ src, bind: true, }}
<!-- Bind size to parent with selectors -->
<div class="wrapper"
    use:image={{ src, bind: '.wrapper', }}
<!-- Bind width to parent with element -->
<div class="wrapper"
    use:image={{ src, bind: { width: '.wrapper' }, }}


Native cloudinary options. See here for official docs For a quick glance