Get help on Discord

Issue with bg parameter in Sanity image URL library for converting PNG to JPG

45 replies
Last updated: Jul 16, 2021
Hey all, thanks for the awesome platform! Love using it in a few of my projects. I have a question about images - if I convert a transparent png to a jpg on the fly, does the bg param not apply to the flattened image? Can’t seem to get it to work (though sure I saw this working in development a few weeks back).. it always sets a black background. Thx
AI Update

Great to hear you're enjoying Sanity! I can help with your image transformation question about the bg parameter.

Yes, the bg parameter should definitely work when converting transparent PNGs to JPG format. According to the Sanity documentation, the bg parameter is designed to "fill in any transparent areas in the image with a color" and accepts hexadecimal color values (RGB, ARGB, RRGGBB, or AARRGGBB).

The black background you're seeing is actually the default behavior when converting transparent images to JPG without specifying a background color. Here are some things to check:

1. Verify your parameter format

Make sure your hex color doesn't include the # symbol - just use the hex value directly:

  • ✅ Correct: ?fm=jpg&bg=ffffff (for white)
  • ✅ Correct: ?fm=jpg&bg=ff0000 (for red)
  • ❌ Wrong: ?fm=jpg&bg=#ffffff

2. Example URL

Here's what a working URL should look like:

https://cdn.sanity.io/images/[project]/[dataset]/[asset].png?fm=jpg&bg=ffffff

This will convert your PNG to JPG and fill transparent areas with white instead of black.

3. Using the image-url helper

If you're using the @sanity/image-url helper library, you can chain methods like this:

imageUrlBuilder(client)
  .image(yourImage)
  .format('jpg')
  .bg('ffffff')
  .url()

4. Check for caching

Since the Sanity CDN caches transformed images, you might be seeing a cached version with the old black background. Try adding a cache-busting parameter or wait a bit for the cache to clear. You could also test with a slightly different size parameter to force a new transformation.

The bg parameter works independently and doesn't require any specific fit mode or other parameters - it simply fills transparent areas with your specified color whenever the image format doesn't support transparency (like JPG).

If you're still seeing black backgrounds after trying these suggestions, double-check that you're actually hitting the new URL with the bg parameter included. Hope this helps!

Hey
user M
have you had a chance to look at this at all? Is it a bug or am I doing something wrong? Many thanks in advance
Hey
user M
have you had a chance to look at this at all? Is it a bug or am I doing something wrong? Many thanks in advance
Hey Andrew! I’m not sure what’s causing this here. What does the url you’ve built for this look like?
Hey! See my first comment for the URL, or do you mean the js I'm passing to the image URL library? Thanks
I mean the js you’re passing to the url library
<figure
                class="logo-inner"
                :style="{
                  backgroundImage: `url('${urlFor(logo.logo)
                    .width(560)
                    .format('jpg')
                    .quality(50)
                    .saturation(-100)
                    .bg('fff')
                    .url()}')`,
                }"
              ></figure>
I’m using vue
the site is live and I’m sure this was working a few weeks ago (I now have black backgrounds on images where pngs are being converted to jpegs)
Looking at the plugin ’s documentation, it does not have a 
.bg()
method. What happens if you remove that and replace 
format('jpg')
with 
auto(format)
?
I want the Png to convert to jpeg because I don't need transparency and there is no png compression
I’m confused, why doesn’t the plugin support the bg parameter defined here in the docs? https://www.sanity.io/docs/image-urls
I may be misunderstanding the use case for this bg feature.. but the behavior I’m after is to “flattten” a transparent image and specify the color with which to fill the alpha channel
ps you see the bg param is outputted in the url - does this not mean it is supported?
Yep, I understand that you’re trying to convert from png. I’m trying to help you troubleshoot by trying different methods. Plus, 
auto(format)
will convert to webP, which is preferable over jpg in most cases as the file size is 25-30% smaller. So hopefully this will at least show that we can get it to convert from png
It doesn’t appear that your application of 
bg()
is having an effect on your image, so I would say based off of that and it’s lack of inclusion in the documentation that it is not supported. I’ll reach out to the creators to confirm.
I just checked the Github repo , and 
bg()
is not supported in 
urlFor()
. I’ll make a note that this is not in line w/the Sanity docs and pass it along for correction.
Thanks for the info! I presumed auto(format) would serve the original image format, sorry
No worries, I feel like it’s a relatively unknown gem.
Bit annoying this though, every image will need to be edited before upload just to perform the flatten to white bg operation
Yeah, it is strange that it’s included in the documentation but not in the approved plugin. I’ll make sure it gets some attention.
Ohh, v. nice!
you can see lower down in the logo and work sections images with black bgs
trust me I wouldn’t have shipped it like this I feel like I’m going mad
Thanks!
Sure I remember adding the bg method and being happy that it was working about a month ago
but guess it couldn’t have changed!
This url works. I changed 
fm=jpg
to 
auto=format
. Maybe try 
auto(format)
so that you can still use the url builder without flattening the images before uploading?
Hey thanks, I'll test that!
Hey
user M
unfortunately that’s not working. The background on the url you sent is from the browser itself - the image is transparent
though it is a webp
I can actually show you this was working when I launched the site because it was cached on my phone
Cached version this morning
Cleared cache and reloaded
I’ll have to find another solution but can you flag this as it looks like something changed with the image pipeline at your end. Thanks for your help
pps bg is supported in the plugin - see line 99
pps bg is supported in the plugin - see line 99
  if (<http://spec.bg|spec.bg>) {
    params.push(`bg=${<http://spec.bg|spec.bg>}`)
  }
Hey, I’ve pushed an update using the auto(‘format’) param and dropped bg() altogether so in modern browsers webp with transparency is served and file size is low as you said. It’s not a perfect solution though because in older safari png will be served without compression but hey ho at least it looks better !
Hey, I’ve pushed an update using the auto(‘format’) param and dropped bg() altogether so in modern browsers webp with transparency is served and file size is low as you said. It’s not a perfect solution though because in older safari png will be served without compression but hey ho at least it looks better !
You’ll notice that it doesn’t actually handle any parameters passed to 
bg
, so, again no, it’s not supported.
Sorry you’ve lost me, this line here appends the params to the url no?
I think the implementation of bg is actually different to what I was after - it seems to be more aligned with aspect ratio. So if you request an image of a different aspect ratio to the source, bg tells it what color the added pixels should be
However as you can see from my screenshots it was working with the flattening of alpha channel too previously

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?