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,
  • space (^4.13.0) - overrides the global CSS variable for the base spacing,
  • 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 provider = 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
provider.theme.update(themeVars);
// you can add a new theme
provider.theme.add(themeVars, 'custom');
// you can enable a new theme
provider.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 the global size, space, time, and angle variables, you can use the theme.size, theme.space, theme.time, and theme.angle utilities, respectively. To access the global primary, neutral, and contrast color variables, use the theme.color, theme.neutral, and theme.contrast utilities, respectively. These variables support setting multiple values and accessing those values by index:

// through the setter
styleProvider.size = [16, 18, 24];

// or via an attribute
<script is="effcss-provider" size="16;18;24;"></script>

// inside the maker, values are available by index
export const maker: TStyleSheetMaker = ({ theme: {size} }) => {
    return {
        '.sz-s': {
            width: size
        },
        '.sz-m': {
            width: size[2]
        },
        '.sz-l': {
            width: size[3]
        },
        '.sz-2xl': {
            // you can set your own multiplier
            width: size[3](2)
        }
    };
};

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 theme.variable utility:

import { TStyleSheetMaker } from 'effcss';

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

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

Arrays of values (v4.12.0)

If the theme parameter has a value in the form of an array, then for each element, except for the first one, of the array, its own CSS variable will be created with a suffix equal to the index of this value. The first element of the array has a zero index, which will be ignored:

const themeVars = {
    custom: ['12px', '24px', '36px']
    // --f0-custom: 12px; --f0-custom-1: 24px; --f0-custom-2: 36px;
};

To access such CSS variables, you can use the theme.variable utility:

export const maker: TStyleSheetMaker = ({ theme: {variable} }) => {
    return {
        '.sz-m': {
            width: variable<TGlobalVars>('custom.1', '100px')
        }
    };
};

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 with version ^4.8.0, you can also override global variables using the same attributes as Style provider (e.g., size, angle, color). These attributes take precedence over the value in values. Starting with version ^4.12.0, you can specify multiple values separated by ;:

<effcss-override size="16;18;24;" color="purple;white;#2192a7"></effcss-override>

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.

Stylesheet tuning (^4.13.0)

Tuning is another way to make your stylesheets flexible. It allows you to define special tuning varibles for external applications.

You can declare tuning variables with its own contract type and implement via theme.tuning utility:

type TMaker = {
    sz: 's' | 'm';
    rounded: '';
    card: {
        bg: 'pri' | 'sec';
        inv: '';
        footer: Record<string, never>;
    }
};

type TMakerTunings = {
    size: number;
    card: {
        color: string;
    }
};

const DEF_TUNING_VAL = 'rgb(82, 119, 119)';

const maker: TStyleSheetMaker = ({ select, theme: { tuning } }) => {
    const selector = select<TMaker>;
    const tuningVar = tuning<TMakerTunings>
    return {
        [selector('sz:s')]: {
            width: '10px'
        },
        [selector('card')]: {
            boxSizing: 'border-box'
        },
        // ...
        div: {
            background: tuningVar('card.color', DEF_TUNING_VAL)
        }
    };
};

Then in applications your stylesheet can be tuned via tune method of Style provider:

styleProvider.dx<TMaker>(maker, []);
const vars = styleProvider.tune<TMakerTunings>({
    card: {
        color: 'oklch(0.85 0.02 196.66)'
    }
}, maker);

const jsx = <div style={vars}>Welcome to the tuned area</div>;

INFO

The Style provider only tunes the stylesheets that you have already created, so make sure you define them through the dx, cx, or use method.