vue-composable

# CSS variables

Expose the CSS variables of your choice to reactive properties. Using MutationObserver (opens new window)

# Parameters

import { useCssVariables } from "vue-composable";

useCssVariables(variables);
useCssVariables(variables, options);
useCssVariables(variables, element, options);

useCssVariables({
  backgroundColor: "color-background", // value is css as --color-background
  foregroundColor: "--color-foreground", // value is css as --color-foreground
  onBackgroundColor: {
    name: "color-on-background",
    value: "red"
  }
});

/**
 * API to assign a value to the css variable
 */
export interface CssVarDefinition {
  name: string;
  value: RefTyped<string>;
}

/**
 * Possible configuration
 */
export type CssVarDef = CssVarDefinition | string;

const defaultOptions = {
  attributes: true,
  childList: true,
  subtree: true
};
Parameters Type Required Default Description
variables Record<string, CssVarDef> true dictionary with the cssVariable name you wish to track/change
options MutationObserverInit false defaultOptions Options passed to MutationObserver.observe MutationObserverInit (opens new window)
element HTMLElement false document.documentElement element to keep track of CssVariables, it will default to document.documentElement if is in a client browser

# State

The useCssVariables function exposes the following reactive states:

import { useCssVariables } from "vue-composable";

const {
  supported,
  observing,
  backgroundColor,
  onBackgroundColor
} = useCssVariables({
  backgroundColor: "color-background",
  onBackgroundColor: {
    name: "color-on-background",
    value: "red"
  }
});

// backgroundColor contains the `--color-background` CSS variable
// onBackgroundColor sets `--color-on-background` CSS variable with the value 'red'
// observing is true

backGroundColor.value = "yellow"; // updates the cssVariable to yellow
State Type Description
supported Boolean Returns true if MutationObserver is supported
observing Ref<Boolean> A value that indicates if the observer is listening to CSS variable changes
...variables Ref<TVariables> Object with the same keys but with reactive CSS variable value

# Methods

The useCssVariables function exposes the following methods:

import { useCssVariables } from "vue-composable";

const { resume, stop } = useCssVariables();
Signature Description
resume Start observing the changes again
stop Stops observing the changes

TIP

Calling stop() will stop observing for changes in the DOM, changes made to the ref will still update/override the style values.

Check the example bellow.

# Example

I am a text with the following color: red

# Code

<template>
  <div>
    <div>
      <label for="foreground-value">
        Override the value for
        <code>--color-foreground</code>:
      </label>
      <input type="text" id="foreground-value" v-model="foreground" />
    </div>

    <div ref="textDiv" class="text" style="color: var(--color-foreground)">
      <span v-if="observing">I am a text with the following color:</span>
      <span v-else>My color will be updated but not my label:</span>
      {{ foreground }}
    </div>

    <div>
      <button type="button" @click="stop" :disabled="!observing">
        Stop observing
      </button>
      <button type="button" @click="resume" :disabled="observing">
        Resume observing
      </button>
    </div>
  </div>
</template>

<script>
import { ref } from "@vue/composition-api";
import { useCssVariables } from "vue-composable";

export default {
  name: "css-variables-example",
  setup() {
    const textDiv = ref(null);

    const { stop, resume, observing, foreground } = useCssVariables(
      {
        foreground: {
          name: "color-foreground",
          value: "red"
        }
      },
      textDiv
    );

    return {
      textDiv,

      observing,
      stop,
      resume,
      observing,
      foreground
    };
  }
};
</script>

<style scoped>
div > div {
  margin-top: 15px;
}

.text {
  margin: 15px 0;
}
</style>

← WebWorker API →