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 stylesheet names,
  • mode - mode for generating scoped selectors (a - data attributes, c - classes),
  • min - mode for generating minified scoped 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,
  • contrast (^4.8.0) - overrides the global CSS variable for the contrast color,
  • neutral (^4.8.0) - overrides the global CSS variable for the neutral color.

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 provider 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 neutral="grey" color="purple" values={overridedValues}>
    <div>...</div>
<effcss-override>`

Starting from version 4.8.0, you can also redefine global variables with the same attributes as the Style provider (for example, size, angle, color). These attributes take precedence over the value from values.

Starting with version ^4.9.0, you can override the color scheme of a component and its contents using the scheme attribute. This attribute can take the values ​​light or dark.

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