javascript.rst

JavaScript

When using the extension Sphinx adds the script sphinx-colorschemed-images.js to the HTML output.

Once the script is loaded in the browser, images added with the cs_image and cs_figure directives will be ready to switch color-schemes based on the prefers-color-scheme CSS media feature. Even when using Sphinx themes that does not read such a feature. In those cases, if the user changes the operating system setting from light to dark and viceversa the javascript module will switch the images accordingly.

Using the NPM package

If you are a theme developer and wanted to have more control over the automatic switching, you might want to use the JavaScript class SphinxColorschemeImageHandler provided with the NPM package sphinx-colorschemed-images.

To do so, npm install the package:

npm i -D sphinx-colorschemed-images

And import the class in your JavaScript module:

import { SphinxColorschemeImageHandler } from "sphinx-colorschemed-images";

If your theme already reads the prefers-color-scheme CSS feature, pass {auto: false} to the class constructor:

const cSchemeImgHdl = SphinxColorschemeImageHandler({auto: false});

And call the method activate whenever you want the images to switch color-schemes:

if (mode !== 'auto')  {  // Assuming it is either 'light' or 'dark'.
    cSchemeImgHdl.activate(mode);
}

This explanation is rather short. You might want to take a look at the source code of the class for completeness, or to a use case in the module cschemes.js of the Nefertiti for Sphinx theme.