Image styling css... what do all these properties do?

ElMiko · 06-09-2025, 11:12 AM

Judging from both MR searches and Google, this question is ripe for a flame war—this is NOT my intent.

I have not been able to discern what the various properties do in practice, both because they appear to behave differently in different apps and because they are described as doing different things by different users.

For example, I've read that for a full-page, portrait mode image

Code:

height: 100%;
width: auto;

But in Sigil (and PageEdit) this merely shows the image at 100% of it's actual size, not fitted to the window.
In callibre, it seems to work until the reading screen is adjusted to 2-page mode, and then it gets horizontally smooshed.

Alternately, I've seen the following recommendation...

Code:

height: 100%;
width: 100%;

Preserves aspect ratio fine in Sigil/PageEdit, but does not limit the image vertically (i.e. widening the window will enlarge the image proportionally, but extend the image beyond th bottom of the window). Meanwhile, in Calibre, it loses its aspect ratio, getting horizontally stretched (but not smooshed).

Another recommendation is...

Code:

height: 100%;
max-width: 100%;

This works in in Sigil/PageEdit, except not being vertically limited when the window is stretched, and it gets horizontally smooshed in Calibre (but not stretched).

Code:

max-height: 100%;
width: 100%;

Again, in Sigil/PageEdit maintains aspect ratio but doesn't vertically limit the image to the window size. In Calibre it stretches horizontally (losing aspect ratio), but WILL resize proportionately when the window is shrunk horizontally.

Also tried max-height/width variants to in include "auto", which again just blows up the image to full resolution in Sigil/PageEdit.

Can someone please explain what I'm doing wrong?

P.S. really unfamiliar with svg wrappers, so not sure I can use those effectively... but shouldn't this be doable with plain old css??

DNSB · 06-09-2025, 01:37 PM

For my purposes, I use an SVG wrapper for full page images which are mostly covers and some large images. For the cover and full page images, vh is set to 99 while the large images get a lower vh value. For small images, I just use a width: xx%; and height: auto;. On one occasion when working on a book which the author wanted to be read in portrait or landscape, I ended up with using media queries to set different values but that was a total PITA to set up. I attached a sample cover image style SVG wrapper. Normally, the styles are in the CSS stylesheet but I've embedded it here just to make it one block. The code is intended to look much the same on either ePub3 or ePub2 renderers.

Code:

  <style type="text/css" title="override_css">
@page {padding: 0pt; margin:0pt}
body {text-align: center; padding:0pt; margin: 0pt; }
.cover {margin: 0; height: 99vh; max-width: 100%; overflow: hidden !important;}
.picWrapper {margin: 0; padding: 0; height: 100%;}
.pic {display: block; margin: auto; width: 100%; position: absolute; top: 0; bottom: 0; left: 0; right: 0;}
</style>
</head>

<body class="cover">
  <div class="picWrapper">
    <svg class="pic" xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 0 1000 1500" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink"><image height="1500" width="1000" xlink:href="../Images/cover.jpeg"/></svg>
  </div>

ElMiko · 06-09-2025, 03:27 PM

@DNSB, I'm sorry... all of that SVG styling is WAY over my head...

It looks like the height is set to 100% in the picWrapper and the svg... and the height/width dimensions are specified at 1000x1500... but what if the image isn't 1000x1500?

Do you have an idea as to why the simple height/width properties are insufficient?

JSWolf · 06-09-2025, 03:33 PM

This is the code I use for a full screen image.

HTML:

Code:

<div class="cover">
<img alt="" class="cover" src="../images/9781101543535_cover.jpg"/>
</div>

CSS:

Code:

body {
  widows: 1;
  orphans: 1;
  margin-top: 0;
  margin-right: 0;
  margin-bottom: 0;
  margin-left: 0;
  text-align: justify;
}
img {
  max-height: 100%;
  max-width: 100%;
}
.cover {
  text-align: center;
  text-indent: 0;
  height: 100%;
}

ElMiko · 06-09-2025, 05:07 PM

Thanks, JSWolf...

I gave this a shot, but it also smooshes the image horizontally in calibre, similar to the

Code:

height: 100%;
width: auto;

styling. And if the window is wider that it is tall, it isn't limited vertically in either Sigil's preview window or PageEdit.

Again, part of the issue here is that it seems that the simple

Code:

height: 100%;
width: auto;

SHOULD work in a certain straightforward way (i.e. fits any given screen up to 100% of the screen's height and automatically adjusts the width proportionately), but it doesn't, and I don't understand why not. And the fact that its idiosyncratic behavior is doubly idiosyncratic depending on whether it's being viewed in Sigil, PageEdit, or Calibre only serves to scramble my brains even further.

KevinH · 06-09-2025, 07:00 PM

As DNSB suggested use an svg wrapper. Sigil will even create an svg wrapper for your cover image when creating the cover.xhtml.

With it your image will scale more properly and you control if aspect ratio is kept or not.

IMHO, svg is worh looking into.

RbnJrg · 06-09-2025, 07:56 PM

Quote:

Originally Posted by ElMiko

For example, I've read that for a full-page, portrait mode image

Code:

height: 100%;
width: auto;

The issue is more complex than you think. First, you should keep in mind that this CSS code works differently depending on whether the e-reader is based on RMSDK (ADE 2.x/3.x) or Webkit/Readium.

If the e-reader is based on Webkit/Readium, "height: 100%" won't work. Or to make it work, more declarations than just "height: 100%" are needed. With this last property, we are telling the e-reader that the image will occupy 100% of the block that contains it. And here the problem arises, because if the containing block is a <div> and this block itself has a "height: 100%" value, for this height to be honored, we have to define that the <body> also has "height: 100%." And this causes more problems than it solves, unless the image has no text either before or after it; this is the typical case of a cover. If it's a cover image, for everything to work under Webkit/Readium you need the following code:

Code:

html, body, div.picture {
   height: 100%;
}

img.cover {
   height: 100%;
   width: auto;
}

And in the .xhtml sheet:

Code:

<div class="picture">
   <img class="cover" alt="" src="../Images/your_image.jpg"/>
</div>

Now the above code will force the image to have a height of 100%, BUT ITS WIDTH CAN BE GREATER THAN 100%. If we change "width: auto" to "width: 100%" in the image's CSS code to avoid this, the image will fill the entire screen but will most likely be distorted. To avoid this, we use the <svg> tag instead of the <img> tag.

The code is greatly simplified if you're working in epub3 since instead of "%" you can use "vh" as the height unit and of that, is not needed to define a height for <html> and <body>. On the other hand, if the e-reader is based on RMSDK, the considerations are the same except that the <html> and <body> tags also don't need to have a height of 100%, but in this case, "vh" can't be used.

There are many more considerations if the image you're working with is going to be included in the middle of a text. In that case, none of the above applies much.

All that said, if what you need is code to handle a cover image, then use the following, which works everywhere (RMSDK, Webkit/Readium, epub2, epub3):

Code:

<head>
  <title>Cover</title>
  <style type="text/css">
    .cover {
          margin: 0;
          height: 99vh;
          max-width: 100%;
          overflow: hidden !important;
    }

    .picWrapper {
          margin: 0;
          padding: 0;
          height: 100%; /* this is for epub2 and ADE */
    }

    @supports(display: flex) { /* but if the ereader supports epub3 */
      .picWrapper {
          height: auto; /*then height is "auto" instead of "100%"
      }
    }
    
    .pic { /* this reserves an space for the svg wrapper equal to the full screen, where the image is going to be inserted */
          display: block;
          margin: auto;
          position: absolute;
          top: 0; bottom: 0; left: 0; right: 0;
    }
  </style>
</head>

<body class="cover">
  <h1 style="display:none" title="Cover" class="sigil_not_in_toc"></h1>

  <div class="picWrapper">
    <svg class="pic" xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 10 600 900" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink">
      <image height="900" width="600" xlink:href="../Images/cover.jpg"/>
    </svg>
  </div>
</body>

Of course, instead of height="900" width="600" you'll employ the height and width in pixels of your image (the same in viewBox). The div.picWrapper under epub2/ADE will have a height of 100% and a width given by the svg wrapper. But under epub3, it will have a height of 0 (

) and a max-width of 100%; under epub3 the height and width is handled by the parameters of the svg wrapper (its maximun height will be able untill 99vh). The above code is complex because contains both, code for epub2 and epub3 and the image will be centered in the screen with the maximum width and height that does not allow distortion.

DNSB · 06-09-2025, 08:01 PM

Quote:

Originally Posted by ElMiko

@DNSB, I'm sorry... all of that SVG styling is WAY over my head...

It looks like the height is set to 100% in the picWrapper and the svg... and the height/width dimensions are specified at 1000x1500... but what if the image isn't 1000x1500?

Do you have an idea as to why the simple height/width properties are insufficient?

You will have to set the "1000, 1500" and the height and width to match. As for why the height/width are insufficient? I gave up on simple height/width due to issues with too many renderers that did their own thing with those settings. Even ADE/RMSDK and WebKit/Readium renderers don't give the same display.

As you can see from @RbnJrg's post, the answer can get even more complex but then copy/paste becomes your friend. Copy the code and then modify as needed (for instance, my cover images are all 1000x1500 or 1125x1500 pixels so I have 2 clips to insert that code.

ElMiko · 06-09-2025, 09:33 PM

Thank you all, especially RbnJrg.

I have some serious reading and re-reading to do. Learning is hard.

Part of the issue here is that the images I'm dealing with are a) not covers, b) not of a consistent height/width, and c) many in number. So I'd hoped there was something that could be generically (and effectively) applied with a simple "class" modification... maybe a <div> if it was being especially intransigient...

But no dice...

RbnJrg · 06-09-2025, 10:29 PM

Quote:

Part of the issue here is that the images I'm dealing with are a) not covers,

On epub2, this is a problem if the height of the image is higher that its width. If the image is wider than it is tall, no problem, with the following code you solve your issues:

Code:

img.all {
  display: inline-block;
  width: 99%; /* or whatever width you wish */
}

.image-setup {
  text-indent: 0;
  text-align: center;
  margin: 0;
}

and in the .xhtml file:

Code:

<p>text text text...</p>
<div class="image-setup">
    <img class="all" src="../Images/your_image.jpg" alt="">
</div>
<p>text text text...</p>

OTOH, under epub3 you can do whatever with images, regardless of whether its height is greater than its width. By setting heights in "vh" and using svg wrappers all problems are solved. And if you employ a bit more complex code, you can even avoid blank spaces originated by images.

Quote:

b) not of a consistent height/width,

As I said, under epub3, that is not a problem; under epub2 as long as the image's width is greater than its height, there's no problem using the code I wrote above. If the height is greater, then you definitely need to use SVG wrappers and set a height "a priori" for the containing block, something like:

Code:

div.wrapper {
   height: 60%; /* This is for ADE */
   height: 60vh; /* This is for Webkit/Readium */
}

and in the .xhtml file:

Code:

<div class="wrapper">
   <svg...><image.../></svg>
</div>

Instead of 60%/60vh, use whatever values you think are most appropriate (don't employ 100%/100vh, at most, since your images are inserted into the body of the text, use 95%/95vh -and you may still need to use a lower value); however, you won't be able to avoid white space in the body of the epub2.

Quote:

c) many in number. So I'd hoped there was something that could be generically (and effectively) applied with a simple "class" modification... maybe a <div> if it was being especially intransigient...

You can appy a general class and to style inline (or with another class) in those images that no follow the rule. For example you can have as general class:

Code:

img.all {
  display: inline-block;
  width: 99%; /* or whatever width you wish */
}

and and as a special class:

Code:

.special_width {
   width: 50%; /* Or whatever you wish */
}

Then, for your special images you employ:

Code:

<div class="image-setup">
    <img class="all special_width" alt="" src="../Images/your_image.jpg" />
</div>

You can do something similar for svg wrappers.

JSWolf · 06-10-2025, 05:52 AM

Quote:

Originally Posted by ElMiko

Thanks, JSWolf...

I gave this a shot, but it also smooshes the image horizontally in calibre, similar to the

Code:

height: 100%;
width: auto;

styling. And if the window is wider that it is tall, it isn't limited vertically in either Sigil's preview window or PageEdit.

Again, part of the issue here is that it seems that the simple

Code:

height: 100%;
width: auto;

SHOULD work in a certain straightforward way (i.e. fits any given screen up to 100% of the screen's height and automatically adjusts the width proportionately), but it doesn't, and I don't understand why not. And the fact that its idiosyncratic behavior is doubly idiosyncratic depending on whether it's being viewed in Sigil, PageEdit, or Calibre only serves to scramble my brains even further.

When using the code I posted, it does not look correct in the preview of the the editor (both calibre or Sigil). It's an issue with QT not respecting %. But it does work correctly in the calibre viewer.

This is as small as the viewer will go while showing the full image.

Click image for larger version

Name: fullscreen.jpg
Views: 15
Size: 11.2 KB
ID: 216120

ElMiko · 06-10-2025, 05:53 AM

Thank you, RbnJrg.

FWIW, I suspect that the non-cover, full page images I'm dealing with may often behave somewhat similarly to cover images in that I tend to place them either at the end or beginning of a chapter as a separate html file to avoid sudden gaps in the text.

Also, in your example

Code:

<div class="wrapper">
   <svg...><image.../></svg>
</div>

does the unspecified styling in the <svg> tag have to include the specific pixel height and width of the image? Or can the aspect ratio be preserved without going through the trouble of looking up the true dimensions of each individual image (again, this is in reference to portrait mode images).

JSWolf · 06-10-2025, 05:59 AM

Quote:

Originally Posted by ElMiko

Thank you, RbnJrg.

FWIW, I suspect that the non-cover, full page images I'm dealing with may often behave somewhat similarly to cover images in that I tend to place them either at the end or beginning of a chapter as a separate html file to avoid sudden gaps in the text.

Also, in your example

Code:

<div class="wrapper">
   <svg...><image.../></svg>
</div>

does the unspecified styling in the <svg> tag have to include the specific pixel height and width of the image? Or can the aspect ratio be preserved without going through the trouble of looking up the true dimensions of each individual image (again, this is in reference to portrait mode images).

If using an unnecessary (IMHO) SVG wrapper, you do need the dimensions of the image because of some software that needs it.

retiredbiker · 06-10-2025, 11:40 AM

One of the things I still use in the Calibre editor is the Insert Image tool. If you are inserting a full page image, it gives you this:

Code:

<div style="page-break-before:always; page-break-after:always; page-break-inside:avoid"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 1128 671" preserveAspectRatio="xMidYMid meet"><image width="1128" height="671" xlink:href="../birdsargue.jpg"/></svg></div>

With just a click on the image file.

It reads the size numbers from the image and puts them in for you. I don't know how widely this works in terms of all the different readers, but it is fine for my Kobo using kepub books.

RbnJrg · 06-10-2025, 11:41 AM

Quote:

Originally Posted by ElMiko

Thank you, RbnJrg.

FWIW, I suspect that the non-cover, full page images I'm dealing with may often behave somewhat similarly to cover images in that I tend to place them either at the end or beginning of a chapter as a separate html file to avoid sudden gaps in the text.

If you are working under epub2, that it's not a bad idea.

Quote:

Also, in your example

Code:

<div class="wrapper">
   <svg...><image.../></svg>
</div>

does the unspecified styling in the <svg> tag have to include the specific pixel height and width of the image?

Yes, it does; you have to include the specific pixel height and width of the image. But that is trivial because Sigil has a plugin that makes all the work for you

You only has to select the image and the code is generated by the plugin. To work with svg wrappers is not a problem at all.

Quote:

Or can the aspect ratio be preserved without going through the trouble of looking up the true dimensions of each individual image (again, this is in reference to portrait mode images).

For each image you must have a particular svg wrapper since all your images have different dimensions. But I repeat you, that is not a problem for you; the Sigil's plugin will do all the work, you won't have to write any line of code (the plugin will write the pixels for you).

06-09-2025, 11:12 AM	#1
ElMiko Evangelist Posts: 427 Karma: 65460 Join Date: Jun 2011 Device: Kindle	Image styling css... what do all these properties do? Judging from both MR searches and Google, this question is ripe for a flame war—this is NOT my intent. I have not been able to discern what the various properties do in practice, both because they appear to behave differently in different apps and because they are described as doing different things by different users. For example, I've read that for a full-page, portrait mode image Code: height: 100%; width: auto; But in Sigil (and PageEdit) this merely shows the image at 100% of it's actual size, not fitted to the window. In callibre, it seems to work until the reading screen is adjusted to 2-page mode, and then it gets horizontally smooshed. Alternately, I've seen the following recommendation... Code: height: 100%; width: 100%; Preserves aspect ratio fine in Sigil/PageEdit, but does not limit the image vertically (i.e. widening the window will enlarge the image proportionally, but extend the image beyond th bottom of the window). Meanwhile, in Calibre, it loses its aspect ratio, getting horizontally stretched (but not smooshed). Another recommendation is... Code: height: 100%; max-width: 100%; This works in in Sigil/PageEdit, except not being vertically limited when the window is stretched, and it gets horizontally smooshed in Calibre (but not stretched). Code: max-height: 100%; width: 100%; Again, in Sigil/PageEdit maintains aspect ratio but doesn't vertically limit the image to the window size. In Calibre it stretches horizontally (losing aspect ratio), but WILL resize proportionately when the window is shrunk horizontally. Also tried max-height/width variants to in include "auto", which again just blows up the image to full resolution in Sigil/PageEdit. Can someone please explain what I'm doing wrong? P.S. really unfamiliar with svg wrappers, so not sure I can use those effectively... but shouldn't this be doable with plain old css??

06-09-2025, 01:37 PM	#2
DNSB Bibliophagist Posts: 45,699 Karma: 168959600 Join Date: Jul 2010 Location: Vancouver Device: Kobo Sage, Libra Colour, Lenovo M8 FHD, Paperwhite 4, Tolino epos	For my purposes, I use an SVG wrapper for full page images which are mostly covers and some large images. For the cover and full page images, vh is set to 99 while the large images get a lower vh value. For small images, I just use a width: xx%; and height: auto;. On one occasion when working on a book which the author wanted to be read in portrait or landscape, I ended up with using media queries to set different values but that was a total PITA to set up. I attached a sample cover image style SVG wrapper. Normally, the styles are in the CSS stylesheet but I've embedded it here just to make it one block. The code is intended to look much the same on either ePub3 or ePub2 renderers. Code: <style type="text/css" title="override_css"> @page {padding: 0pt; margin:0pt} body {text-align: center; padding:0pt; margin: 0pt; } .cover {margin: 0; height: 99vh; max-width: 100%; overflow: hidden !important;} .picWrapper {margin: 0; padding: 0; height: 100%;} .pic {display: block; margin: auto; width: 100%; position: absolute; top: 0; bottom: 0; left: 0; right: 0;} </style> </head> <body class="cover"> <div class="picWrapper"> <svg class="pic" xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 0 1000 1500" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink"><image height="1500" width="1000" xlink:href="../Images/cover.jpeg"/></svg> </div>

06-09-2025, 05:07 PM	#5
ElMiko Evangelist Posts: 427 Karma: 65460 Join Date: Jun 2011 Device: Kindle	Thanks, JSWolf... I gave this a shot, but it also smooshes the image horizontally in calibre, similar to the Code: height: 100%; width: auto; styling. And if the window is wider that it is tall, it isn't limited vertically in either Sigil's preview window or PageEdit. Again, part of the issue here is that it seems that the simple Code: height: 100%; width: auto; SHOULD work in a certain straightforward way (i.e. fits any given screen up to 100% of the screen's height and automatically adjusts the width proportionately), but it doesn't, and I don't understand why not. And the fact that its idiosyncratic behavior is doubly idiosyncratic depending on whether it's being viewed in Sigil, PageEdit, or Calibre only serves to scramble my brains even further.

06-09-2025, 07:00 PM	#6
KevinH Sigil Developer Posts: 8,683 Karma: 5703586 Join Date: Nov 2009 Device: many	As DNSB suggested use an svg wrapper. Sigil will even create an svg wrapper for your cover image when creating the cover.xhtml. With it your image will scale more properly and you control if aspect ratio is kept or not. IMHO, svg is worh looking into. Last edited by KevinH; 06-09-2025 at 09:26 PM.

06-10-2025, 05:53 AM	#12
ElMiko Evangelist Posts: 427 Karma: 65460 Join Date: Jun 2011 Device: Kindle	Thank you, RbnJrg. FWIW, I suspect that the non-cover, full page images I'm dealing with may often behave somewhat similarly to cover images in that I tend to place them either at the end or beginning of a chapter as a separate html file to avoid sudden gaps in the text. Also, in your example Code: <div class="wrapper"> <svg...><image.../></svg> </div> does the unspecified styling in the <svg> tag have to include the specific pixel height and width of the image? Or can the aspect ratio be preserved without going through the trouble of looking up the true dimensions of each individual image (again, this is in reference to portrait mode images).

06-09-2025, 03:27 PM	#3
ElMiko Evangelist Posts: 427 Karma: 65460 Join Date: Jun 2011 Device: Kindle	@DNSB, I'm sorry... all of that SVG styling is WAY over my head... It looks like the height is set to 100% in the picWrapper and the svg... and the height/width dimensions are specified at 1000x1500... but what if the image isn't 1000x1500? Do you have an idea as to why the simple height/width properties are insufficient?

06-09-2025, 09:33 PM	#9
ElMiko Evangelist Posts: 427 Karma: 65460 Join Date: Jun 2011 Device: Kindle	Thank you all, especially RbnJrg. I have some serious reading and re-reading to do. Learning is hard. Part of the issue here is that the images I'm dealing with are a) not covers, b) not of a consistent height/width, and c) many in number. So I'd hoped there was something that could be generically (and effectively) applied with a simple "class" modification... maybe a <div> if it was being especially intransigient... But no dice...

06-10-2025, 11:40 AM	#14
retiredbiker Evangelist Posts: 448 Karma: 3886916 Join Date: May 2013 Location: Ontario, Canada Device: Kindle KB, Oasis, Pop_Os!, Jutoh, Kobo Forma	One of the things I still use in the Calibre editor is the Insert Image tool. If you are inserting a full page image, it gives you this: Code: <div style="page-break-before:always; page-break-after:always; page-break-inside:avoid"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 1128 671" preserveAspectRatio="xMidYMid meet"><image width="1128" height="671" xlink:href="../birdsargue.jpg"/></svg></div> With just a click on the image file. It reads the size numbers from the image and puts them in for you. I don't know how widely this works in terms of all the different readers, but it is fine for my Kobo using kepub books.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
CSS Styling based on class/existing styling	1ily	Calibre	8	03-17-2025 06:37 AM
Incorrect styling with specific CSS	quiris	Marvin	9	07-04-2016 01:04 PM
Missing CSS properties	roger64	KOReader	0	06-01-2016 06:39 AM
inspect image properties /replace image	cybmole	Sigil	6	02-05-2013 12:46 PM
Unsetting properties in CSS	Jellby	ePub	2	06-03-2009 04:29 AM

Advert

Advert