[css-values-4][cssom] Proposal to allow retrieval of sub-pixel border values

Background

Some properties support sub-pixels. WebKit.org has a breakdown in the LayoutUnit - Use cases section of their site.

Other properties, like border-width, don't support sub-pixels. John Resig - Sub-Pixel Problems in CSS is a short read that summarizes the issue well.

In Distance Units: the <length> type, the specification describes the method of rounding computed values such as border-width that don't use sub-pixels:

To snap a length as a border width given a <length> len:

1. Assert: len is non-negative.
2. If len is an integer number of device pixels, do nothing.
3. If len is greater than zero, but less than 1 device pixel, round len up to 1 device pixel.
4. If len is greater than 1 device pixel, round it down to the nearest integer number of device pixels.

This is the intended and currently-implemented behavior, and I'm not proposing that it changes for elements rendered on-screen.

Proposal

Implement an optional, opt-in feature to programmatically retrieve sub-pixel values when using functions such as getComputedStyle.

// The style is calculated using sub-pixels for all properties. Does not change the rendering behavior.
const computedStyle = getComputedStyle(element, options: { useSubPixels: true })

This would not change the behavior of how elements are rendered. Properties like border-width that don't render with sub-pixels would still not render with sub-pixels.

This would simply allow developers to retrieve the sub-pixel values of properties such as border-width before they are rounded. The browsers have access to this information, and it would be helpful if developers were able to programmatically access it too.

useSubPixels could apply to all properties, or there could be more granularity. I'm most interested in it applying to border-width.

Reproducible Example

The contents of these two files are included below:

1. puppeteer-script.js
2. package.json

The script uses Puppeteer, a library created and maintained by the Chrome DevTools team, to demonstrate how border-width values change due to sub-pixel rounding.

Puppeteer needs to run in a server environment, so the script can't be run in the browser. I've included detailed instructions on how to set up and run this script, in case anyone is reading this but isn't familiar with all the tools being used. If you're familiar with everything, you could skip reading these steps and go straight to running the script. The instructions are for Windows, but the process should be similar on other operators systems.

Steps to Run the Script

1. Create a folder anywhere on your computer, and save the attached puppeteer-script.js in that folder.

2. Install the latest stable version of Node.js by using the prebuilt installer found here. No changes beyond the default installation are necessary.

3. Open the command line interface by typing cmd or Command Prompt in your Windows Start menu/search field.

4. In the command line interface, verify that Node has been globally installed by typing node -v and pressing enter. Then, type and enter npm -v (npm is the Node Package Manager). Both commands should display the version number of the installed programs.

5. Once installation is confirmed, in the command line interface, change directories so you're in the folder created in step 1. For example, if you created the folder on your Desktop and named it Test, you could type cd Desktop/Test to navigate there.

6. Once you've navigated to the folder where puppeteer-script.js is saved, type and enter the command npm install puppeteer to install the latest version of Puppeteer. Once the installation is complete, the folder should have a few new items: a node_modules folder, a package.json file, and a package-lock.json file.

7. Update your package.json file to look like the version I've included here by adding "type": "module", to the JSON object. This will make it so you can call import puppeteer from 'puppeteer' in the script.

8. In the command line interface (still within the folder you created in step 1), type node puppeteer-script.js to run the script.

The command line interface should display the following:

border-left-width would have been 1800px * 0.0025 = 4.50px if sub-pixels were enabled
border-left-width is actually 4px since it has been rounded down
The computed width is 400.5px and the rect width is 400.5px

Explanation of the Script

The script created a page with a width of 1800px, and an element with border-left-width: 0.25vw, which means 0.25% of the screen's width. The sub-pixel value of border-left-width is 1800px * 0.0025 = 4.50px. However, per the specification, this value was rounded down to 4px, as expected.

For a bit of added information, the script also shows that the element's width based on the results of getComputedStyle and getBoundingClientRect uses sub-pixels. This was added to show that it would be consistent with the behavior of other properties if some properties, like border-width, could also return sub-pixels on the developer side. border-width contributes to the width of the element, and while its possible to use calculate the sub-pixel value based on information like this, it would be much more straight-forward and consistent to be able to retrieve it directly.

Script Code

puppeteer-script.js:

'use strict'

import puppeteer from "puppeteer"

(async function main()
{
    try
    {
        const html = `<div id = "something"></div>`
        const css = `#something
        {
            box-sizing: border-box;
            width: 22.25vw;
            border-top: 96px solid blue;
            border-left: 0.25vw solid red;
            position: absolute;
        }`

        const browser = await puppeteer.launch({ headless: true })
        const page = await browser.newPage()

        await page.setViewport({ width: 1800, height: 2400 })
        await page.setContent(html)
        await page.addStyleTag({ content: css })

        const results = await page.evaluate(() =>
        {
            const element = document.getElementById('something')
            const computedStyle = getComputedStyle(element)
            const borderLeftWidth = computedStyle.getPropertyValue('border-left-width')
            const computedWidth = computedStyle.getPropertyValue('width')
            const rectWidth = element.getBoundingClientRect().width
            
            return {
                borderLeftWidth: borderLeftWidth,
                computedWidth: computedWidth,
                rectWidth: rectWidth
            }
        })

        const { borderLeftWidth, computedWidth, rectWidth } = results

        console.log(`\nborder-left-width would have been 1800px * 0.0025 = 4.50px if sub-pixels were enabled`)
        console.log(`\nborder-left-width is actually ${borderLeftWidth} since it has been rounded down`)
        console.log(`\nThe computed width is ${computedWidth} and the rect width is ${rectWidth}px`)

        await page.close()
        await browser.close()
    }
    catch (error)
    {
        console.error(error)
    }
})()

package.json:

{
  "type": "module",
  "dependencies":
  {
    "puppeteer": "^22.15.0"
  }
}

Example of Proposed Feature

If this feature were added, the element created in the script above would still render with a border-left-width of 4px, but I would be able to call the following:

// The style is calculated using sub-pixels for all properties. Does not change the rendering behavior.
const computedStyle = getComputedStyle(element, options: { useSubPixels: true })
const borderLeftWidth = computedStyle.getPropertyValue('border-left-width')

And receive a value of 4.50px for border-left-width - the sub-pixel value before rounding. The rendered border-left-width is still 4px, but the useSubPixels parameter allows me to compute the value as if it hadn't been rounded. Since the browser already has this information, it will hopefully not be difficult to implement.

[Loirooriol]

The browsers have access to this information

Well, it's in the cascade I guess, but it's lost in the computed value. So exposing it via getComputedStyle doesn't really make sense.

@Loirooriol Thanks for the response. Can you explain more what you mean about it being lost in the computed value? Doesn't getComputedStyle begin with the original, un-rounded value?

Otherwise, could you imagine a better way to expose this information other than having to parse the CSS itself?

[Loirooriol]

getComputedStyle begins with the computed value, and sometimes resolves it further to used values or whatever.
Here the computed value has already been snapped. See https://drafts.csswg.org/css-backgrounds-3/#border-width

Computed value: absolute length, snapped as a border width; zero if the border style is none or hidden

Got it, thanks. Is there any more appropriate way to expose the information? For example, something that might prevent the computed value from snapping to the whole pixel number, or something along those lines. That particular example may not work since the computed value is likely used for rendering the actual element, but just thinking out loud. If getComputedStyle isn't workable, maybe a function along the lines of getBoundingClientRect?

[tabatkins]

I'm sorry, but I don't see any explanation in your post about why you want the unrounded border sizes. If you're trying to use those sizes for something else, such as to make another element match the size, you presumably want the size that's actually used on the page. What would having the unrounded info help you with?

(Unrelated: I've noticed a lot of issues lately showing up with this long, multi-heading style, and it seems new and unusual. Did you perhaps use an LLM to generate the initial text?)

@tabatkins Thanks for the reply. I'm working on a project that, in part, determines not just the size of the element but what properties contribute to its size. With that in mind, it would be helpful and consistent with other methods like getBoundingClientRect if border-width could return sub-pixel values, just like width and other related properties do.

About the style, I'm not sure about others, but I didn't use an LLM. I initially filed it as a feature request on the Chromium project, but the Chromium team suggested that it should be filed as an issue with the CSSWG. The Chromium bug report/feature request form has required sections that have to be filled out, and then uses those section titles as headings in the generated post. Initially, my Chromium issue had limited information, but I incrementally added more in the comments. When writing this issue, I combined everything to give you all the information I thought would be helpful, and I used the Chromium-style headings because I think they help break up the content and make it easier to read.

[Loirooriol]

Assuming 1dppx, border-width: 0.5px will result in a border that is 1px thick. Why do you want to get 0.5px, it won't match reality.

I'm hoping to work with the sub-pixel value for two main reasons. The first reason is related to my project, which I'll admit is for sure a specific scenario. The second is that I think it would be consistent with the behavior of other methods, and that there are existing reasons to be interested in sub-pixel values, even if screens can't render them yet.

Specific to my project, if I'm trying to find an element on the page with a specified border-left-width of 0.25vw, then the current behavior makes it difficult, if not impossible, to know when I've found it.

For example, on a screen with a width of 1800px, the sub-pixel value would be 4.50px, and it would be snapped to 4px. When I compute the style and see 4px, it could mean that border-left-width was 0.25vw and snapped, or it could mean that it was 0.225vw with no need to be snapped, since 0.225vw on an 1800px wide screen is 4px. There's no practical way to know. You could make an estimate based on other properties, but it still wouldn't be certain.

Your point that it doesn't match reality is correct, and that's something that has to be taken into account. But it would be a more complete picture to have access to pre-snap values. It's a small difference on a per-element basis, but if you're working with a large number of elements, the differences add up.

In regard to consistency, given how precise methods like getBoundingClientRect are, and how other properties like height and width in getComputedStyle use sub-pixels, it would be great be able to work with sub-pixel measurements for other size-related properties like border-width.

For example, in the script above, I set width: 22.25vw, which comes out to 400.50px on an 1800px screen. Even though sub-pixels can't be rendered, and the actual width in reality isn't 400.50px, I'm still able to see the sub-pixel value.

Sub-pixels are useful for techniques like anti-aliasing and increasing a screen's effective resolution. This goes to show that there are reasons to be interested in the sub-pixel values, even if modern screens aren't able to render them yet. Since this information is available for other properties, I think it makes sense to make it available for properties like border-width.

[Loirooriol]

I don't understand why you are trying to find an element by checking the border width. Why not just add an ID or class?

Even though sub-pixels can't be rendered

Not necessarily, since 1px may have multiple device pixels.

Also, if you have 2 elements with width: 50.5px with 1dppx, they will typically add up to 101px, since internally all major browsers can store that amount (Gecko has a precision of 1px/60, Blink 1px/64, old Edge was 1px/100 I think).

This is not what happens for borders, because borders are snapped. Borders behave in a different way, browsers store the snapped amount, not the original one. So trying to be consistent doesn't work.

<div style="border: solid; border-width: 50px 100.5px; width: 0"></div>
<div style="background: magenta; width: 100.5px; height: 100px; float: left"></div>
<div style="background: magenta; width: 100.5px; height: 100px; float: left"></div>

Thanks for the visual example! That's good to know.

I think the best way to describe my question at this point, given what we've discussed so far, is: why wouldn't border-width support sub-pixels?

Your example shows that sub-pixels can be rendered and have a visual impact on the layout. And even otherwise, there are uses for the information like for anti-aliasing.

The spec mentions:

While the exact supported precision of numeric values, and how they are rounded to match that precision, is generally implementation-defined, <length>s in border-width and a few other properties are rounded in a specific fashion to ensure reasonable visual display.

In other words, since border-width is being rounded, every user agent should round it the same way. But why does border-width have to be rounded/snapped in the first place?

Clip rects, overflow rects, scroll height and width, margin, padding, location, and size of rendered elements all use sub-pixels. border-width also contributes to the space taken up by an element, but it's snapped to a whole pixel. That's along the lines of what I meant when I mentioned consistency. What drawbacks would there be to supporting sub-pixels in border-width?

[schenney-chromium]

Borders are snapped to provide crisp lines on what are often narrow widths. Without snapping, a 1px border drawn at sub-pixel locations will anti-alias and result in a very different visual appearance. Even worse, the appearance of the same border description may vary on different sides of the element which is very undesirable Things get even worse at sub-pixel rendering when property values like double or dashed are used.