API

Qtheme: ThemeChanger

init

Initialize theme from localStorage if exists with init else provided default theme.

Qtheme will save theme in localStorage. You can change default key with token option. Will be applied to common atoms as well if provided.

    import {Qtheme, ThemeAtom, InitRootAtomOptions} from '@quak.lib/qtheme'
    
    interface InitRootAtomOptions {
      commonAtoms: ThemeAtom[]; // []
      token: string; // 'Qtheme'
      commonToken: string; // 'Qtheme-common'
      generateCSS: boolean; // true
    }
    
    Qtheme.init(defaultTheme: Theme, options?: Partial<InitRootAtomOptions>)  
    
    
    // Example
    import {Qtheme} from '@quak.lib/qtheme'
    import {yourDefaultTheme, yourCommonAtoms} from '/path/to/your/themes'
    
    Qtheme.init(yourDefaultTheme, {commonAtoms: yourCommonAtoms})
                        

setTheme

Initialize or change theme with setTheme.

Qtheme will save theme in localStorage. You can change default key with token option.

    import {Qtheme, Theme, SetRootAtomOptions} from '@quak.lib/qtheme'

    interface SetRootAtomOptions {
      token: string; // 'Qtheme'
      generateCSS: boolean; // true
    }
    
    Qtheme.setTheme(theme: Theme, options?: Partial<SetRootAtomsOptions>)     
    
    
    // Example
    import {Qtheme} from '@quak.lib/qtheme'
    import {yourTheme} from '/path/to/your/themes'
    
    Qtheme.setTheme(yourTheme)      
                        

getTheme

Use getTheme to get current theme (from localStorage).

You can initialize theme on app start with that.

    import {Qtheme, Theme} from '@quak.lib/qtheme'

    Qtheme.getTheme(token?: string): Theme | null  
    
    
    // Example
    import {Qtheme, Theme} from '@quak.lib/qtheme'
    
    const theme: Theme | null = Qtheme.getTheme()         
                        

setCommonAtoms

You can set common theme atoms with setCommonAtoms.

It will apply theme atoms and save them in localStorage.

You can change default key with commonToken option.

    import {Qtheme, ThemeAtom, SetRootAtomOptions} from '@quak.lib/qtheme'
    
    interface SetRootAtomsOptions {
      commonToken: string; // 'Qtheme-common'
      generateCSS: boolean; // true
    }
    
    Qtheme.setCommonAtoms(atoms: ThemeAtom[], options?: Partial<SetRootAtomsOptions>) 
    
    
    // Example
    import {Qtheme} from '@quak.lib/qtheme'
    import {yourCommonAtoms} from '/path/to/your/themes'
    
    Qtheme.setCommonAtoms(yourCommonAtoms)              
                        

getCommonAtoms

Use getCommonAtoms to get current common theme atoms (from localStorage).

You can initialize common theme atoms on app start with that.

    import {Qtheme, ThemeAtom} from '@quak.lib/qtheme'
        
    Qtheme.getCommonAtoms(commonToken?: string): ThemeAtom[] | null   
    
    // Example
    import {Qtheme, ThemeAtom} from '@quak.lib/qtheme'
    
    const commonAtoms: ThemeAtom[] | null = Qtheme.getCommonAtoms()           
                        

ThemeChanger

ThemeChanger is an interface for Qtheme object.

You can use it to change theme or common theme atoms.

    
    export interface ThemeChanger {
      /**
       * @description Initializes default theme (from localStorage else defaultTheme) and common atoms
       * @param defaultTheme
       * @param options
       */
      init(defaultTheme: Theme, options?: Partial<InitRootAtomsOptions>): void;
    
      /**
       * @description Sets provided css root atoms to the current theme
       * @sideEffect will update LocalStorage as well, key=options.token, defaults to 'Qtheme'              
       * @param theme
       * @param options
       */
      setTheme(theme: Theme, options?: Partial<SetRootAtomsOptions>): void;
    
      /**
       * @description Returns current theme from localStorage
       * @param themeToken defaults to 'Qtheme'
       */
      getTheme(themeToken?: string): Theme | null;
    
      /**
       * @description Updates common atoms
       * @sideEffect will update LocalStorage as well, key=options.commonToken, defaults to 'Qtheme-common'           
       * @param atoms
       * @param options
       */
      setCommonAtoms(atoms: ThemeAtom[], options?: Partial<SetRootAtomsOptions>): void;
    
      /**
       * @description Returns common atoms from localStorage
       * @param commonThemeToken defaults to 'Qtheme-common'
       */
      getCommonAtoms(commonThemeToken?: string): ThemeAtom[] | null;
    }
                        

Theme

Theme is an interface for your theme. It contains name and atoms.

Atoms are simple key-value concepts.

You can use them to set css variables.

    /**
     * Theme interface, base on it your theme or 
     * extend this interface with your own properties.          
     */
    export interface Theme {
      name: string;
      atoms: ThemeAtom[];
    }
                        

ThemeAtom

ThemeAtom is an interface for your theme atom. It contains name and value.

Value can be a css value or a css-property-name:css value.

    /**
     * Base css :root variable [key, value]
     */
    export type AtomName = string;
    export type AtomValue = string | CSSProps | any; // any for better work with React CSSProperties, intelisense still works
    export type ThemeAtom = [AtomName, AtomValue];             
                        

CSSProps

CSSProps is an interface for your css properties as atom values.

It helps with hints in your IDE when you type css properties.

    // JSStyle is Qtheme inner type with CSS properties and theirs values    
    // You can import JSStyle as well, but there is no reason to do that
    import { JSStyle } from '@quak.lib/qtheme'  
    
    // It describes CSS properties and theirs values with camelCase support
    // You can use "kebab-case", but it will not be supported by IDE hints 
    
    // any for better work with React CSSProperties (based on cssstyle), intelisense still works    
    type CSSProps = JSStyle & Partial<Record<string, string | number>> | any
    
    // To import CSSProps you can use:
    import { CSSProps } from '@quak.lib/qtheme'  
    
    // IDE will show hints for CSS properties
    // If want to use some vendor one simply use string
    const cssProps: CSSProps = {
        backgroundColor: 'red',
        '-webkit-font-smoothing': 'antialiased,
        '-moz-osx-font-smoothing': 'grayscale'
    } 
                        

SetRootAtomOptions

InitRootAtomsOptions is an interface for init method. SetRootAtomsOptions is an interface for setTheme and setCommonAtoms methods.

It contains generateCSS and token properties to:

• generateCSS - boolean, if true, Qtheme will generate CSS for you
• token - string, key for localStorage
• commonToken - string, key for localStorage for common atoms
• commonToken|token + each will be style tag id if generateCSS true

    export interface SetRootAtomsOptions {
      generateCSS: boolean; // true
      token: string; // 'Qtheme'
      commonToken: string; // 'Qtheme-common'           
    }
    
    export interface InitRootAtomsOptions extends SetRootAtomsOptions {
        commonAtoms: ThemeAtom[];
    }
                        

Auto-generated CSS

Qtheme can generate CSS for you(for theme atoms), so you don't have to write it by yourself.

It's optional, you can use it or not.

   
    import {ThemeAtom} from '@quak.lib/qtheme'
    
    const yourThemeAtoms: ThemeAtom[] = [
      // Only --root-variable: value will be generated
      ['primary', 'dodgerblue'],
      ['accent', 'pink'],
      ['bg', '#333'],
      ['bg-inner', '#222'],
      
      // --root-variable: value will be generated
      // CSS class .bg-color will be generated
      ['bg-color', 'background-color:var(--bg)'],
      ['bg-accent', 'background-color:var(--accent)'],              
      ['text-color', 'color:#fff'],
      ['text-accent', 'color:var(--accent)'],
      
      // Compound
      // only CSS class .bg-accent-inner will be generated
      ['bg-accent-inner', {
        'color': 'var(--text-accent)',
        'background-color': 'var(--bg-accent)'
      }]
    ];
                            

If you want to use auto-generated CSS classes then

you need to provide color: or background-color: or anything you need.

Just follow regular CSS syntax.