Skip to content

Stock Photos ​

Sveltia CMS includes built-in support for integrating free stock photo services directly into the media storage. This allows content creators to easily search for and insert high-quality images into their content without leaving the CMS interface.

Supported Services ​

Currently, Sveltia CMS supports the following free stock photo providers:

Future Plans

More providers, including paid stock photo services, may be added in future releases.

Note on Lorem Picsum ​

  • You don’t need an API key to use Lorem Picsum, so it’s the easiest option to get started with stock photos in Sveltia CMS.
  • Their pictures are mainly for placeholder use, so they may not be suitable for all types of content. However, they can be a great option for testing or when you need generic images without specific themes.
  • Their pictures are CC0 licensed, which means they are free to use without giving credit to the creator.
  • You can access 300 random pictures quickly, but you cannot search for specific images using keywords. Due to the nature of the service, the images do not have tags or captions.
  • Unfortunately, there is no alternative text for the images because they do not have tags or captions. This makes them inaccessible to some users.

Non-hotlinking Providers ​

Pexels and Pixabay don’t allow hotlinking, so they need the internal media storage. They are disabled if the internal media storage is disabled because the configuration lacks the media_folder option. They are also hidden for a field where the internal media storage is disabled with media_libraries.default: false.

Requirements ​

Except for Lorem Picsum, which does not require an API key, you must obtain an API key for each stock photo service you wish to use. Register for developer accounts at the following links to get your API keys:

CSP ​

If your site uses a Content Security Policy (CSP), you may need to update it to allow requests to stock photo providers. See the CSP documentation for more details.

Configuration ​

No additional configuration is required to enable stock photo providers, as they are included by default. However, developers can customize which providers are available or disable them entirely.

To enable or disable specific stock photo providers, you can modify the providers array in the media_libraries section of your config.yml file. For example, to enable only Unsplash, you would configure it as follows:

yaml
media_libraries:
  stock_assets:
    providers:
      - unsplash
toml
[media_libraries.stock_assets]
providers = ["unsplash"]
json
{
  "media_libraries": {
    "stock_assets": {
      "providers": ["unsplash"]
    }
  }
}
js
{
  media_libraries: {
    stock_assets: {
      providers: ["unsplash"],
    },
  },
}

To disable stock photo providers, you can set the providers array to be empty in the media_libraries section of your config.yml file, as shown below:

yaml
media_libraries:
  stock_assets:
    providers: []
toml
[media_libraries.stock_assets]
providers = []
json
{
  "media_libraries": {
    "stock_assets": {
      "providers": []
    }
  }
}
js
{
  media_libraries: {
    stock_assets: {
      providers: [],
    },
  },
}

Setting stock_assets to false also disables all the providers.

The stock_assets option can be set for an individual Image field under its media_libraries option as well. The field-level options are merged over the top-level ones, so a field can offer a different set of providers, or none.

Using Stock Photos ​

Stock photos can be accessed directly from the Image field in the Sveltia CMS interface. When opening the Select Images dialog, stock photo options are shown alongside the existing media storage.

Select the desired stock photo provider and provide an API key to enable the service. API keys are stored securely in the browser’s local storage, so users don’t need to enter them every time. Lorem Picsum doesn’t require an API key, so it will be available immediately without any configuration.

By default, curated images from each provider are available for quick access. You can also use the search functionality to find specific images based on keywords. Lorem Picsum doesn’t support searching as mentioned earlier, so it will only show random images.

Once the desired image is found, simply select it, and it will be inserted into the content just like any other media asset.

Note that some providers require hotlinking to the image’s original URL, while others disallow hotlinking. Sveltia CMS handles this automatically based on the provider’s policies. If necessary, it downloads the image to the media storage.

When an Unsplash photo is inserted, Sveltia CMS also notifies Unsplash of the download using your API key, as the Unsplash API guidelines require.

Photo Credits ​

Unsplash requires you to credit the photographer when you use its API, and Pexels and Pixabay appreciate it. After you select a photo from one of them, the Photo Credit dialog shows the credit as HTML, e.g. Photo by <a href="…">Jane Doe</a> on <a href="…">Unsplash</a>. Lorem Picsum photos need no credit, so the dialog doesn’t appear for them.

The dialog offers these buttons:

  • Insert to [field], e.g. Insert to Body: Appends the credit as a new paragraph at the end of a Markdown or RichText field of the entry. The credit is written with Markdown links, or as HTML in a field with the html format.
  • Insert: Appears instead when the image is selected in the built-in image editor component of a RichText field. It adds the credit to the image’s caption.
  • Copy: Copies the credit HTML to the clipboard. Its menu offers Copy as Markdown, which copies the credit with Markdown links instead.

Insert to [field] uses the first top-level Markdown or RichText field that takes multiple lines and can be edited in the current locale. A field within a List or Object field isn’t used. When there’s no such field, or the image is selected in an editor component without a caption, the dialog only offers to copy the credit.

A custom editor component can take the credit as well. The Insert button appears for an Image or File field in a component that also has a String or Text field named caption.

If the caption already holds a stock photo credit, e.g. because the image was swapped for another stock photo, Insert replaces that credit and keeps the rest of the caption.

Multi-user setups

If your CMS instance is used by multiple users, the administrator needs to distribute an API key to all users to let them use the stock photo feature.

Alternatively, each user can provide their own API key. However, this is not recommended for instances with non-technical end users because generating and managing API keys may be challenging for them.