Customization

The behavior of the Style provider can be customized by passing parameters to the useStyleProvider function. Additionally, you can override the global variables of the default theme or create your own theme.

Parameters of useStyleProvider

The useStyleProvider function accepts the following parameters:

• emulate - forcibly creates a Style provider emulation in the browser (no need to pass it on the server, the emulation will be created automatically),
• noscript - after converting the Style provider emulation to a string, removes the script from it, leaving only the initial CSS styles (useful for SSG),
• global (^4.2.0) - save and use the Style provider as global object,
• attrs - Style provider attributes:
  • pre - prefix for style sheet names,
  • mode - mode for generating BEM selectors (a - data attributes, c - classes),
  • min - mode for generating minified BEM selectors (boolean attribute),
  • size - overrides the global CSS variable for the base size,
  • time - overrides the global CSS variable for the base time,
  • angle - overrides the global CSS variable for the base angle,
  • color (^4.3.0) - overrides the global CSS variable for the base color,
  • easing (^4.4.0) - overrides the global CSS variable for the base easing function.

Theming

The EffCSS theme is a set of global CSS variables.

Themes are created/updated/deleted using the theme controller object, which is available from the theme property of the Style consumer object:

import { useStyleProvider } from 'effcss';

const consumer = useStyleProvider();
const themeVars = {
    size: 18,
    time: 150,
    angle: 15,
    color: 'green',
    sz: {
        s: 10,
        m: 20,
        l: 30
    },
    coef: {
        1: 0.05,
        32: 220,
        15: 1.9
    },
    hue: {
        sec: 220,
    },
    $light: {
        lightness: {
            bg: {
                s: 0.785
            }
        },
        chroma: {
            fg: {
                rich: 0.145
            }
        }
    }
};
// you can override the default theme variables
consumer.theme.update(themeVars);
// you can add a new theme
consumer.theme.add(themeVars, 'custom');
// you can enable a new theme
consumer.theme.switch('custom');

Note the special top-level keys $light and $dark, which set the context of variables for the light and dark color schemes, respectively.

To access global variables for size, time, and angle, use the size, time, and angle utilities, respectively.

To access global variable for color, use color.root utility.

Numerical coefficients and their ranges are available through the coef utility.

The hue, lightness, and chroma objects are used by the palette utility.

To use arbitrary theme variables in your StyleSheet maker functions, use the themeVar utility:

import { TStyleSheetMaker } from 'effcss';

type TGlobalVars = {
    sz: {
        s: string;
        m: string;
        l: string;
    }
};

export const maker: TStyleSheetMaker = ({ themeVar }) => {
    return {
        '.sz-m': {
            width: themeVar<TGlobalVars>('sz.m', '100px') // '100px' - fallback value
        }
    };
};

Multitheming

To use a theme other than the global one for a specific HTML element, call the use function without arguments and pass the modifier with the desired theme to the resulting resolver:

import type { TBaseStyleSheetMaker } from 'effcss';
import { useStyleProvider } from 'effcss';

const consumer = useStyleProvider();
const [resolver] = consumer.use();
const attrs = resolver<TBaseStyleSheetMaker>('..theme.custom');

Overriding global variables (^4.5.0)

Instead of defining multiple themes, you can set and redefine global variables for individual parts of the layout using the web component effcss-override. To do this, pass to the values attribute a string prepared using the prepareOverrideValues utility:

import { prepareOverrideValues } from 'effcss';

const overridedValues = prepareOverrideValues({
    size: 32,
    hue: {
        pri: 10
    },
    $light: {
        lightness: {
            bg: {
                xl: 0.95
            }
        }
    }
});

export const Component = () => <effcss-override values={overridedValues}>
    <div>...</div>
<effcss-override>`

The effcss-override component has the display:contents; style by default, so as not to cause changes in the layout.