Reference
Configuration
Everything can be adjusted through an attribute on the script tag, or through
V.config before the first render. None of it is required: the library works with no
configuration at all.
V.config
| Option | Default | What it does |
|---|---|---|
prefix | 'v-' | The attribute prefix |
autoStart | true | Starts the library when the script loads |
autoDiscover | true | Watches the DOM and initializes elements created later |
root | null | The root being watched. With no value, it uses document.body |
devtools | false | Detailed console warnings and named anchor comments |
baseURL | '' | Base URL for the declarative requests |
globals | {} | Extra values allowed inside expressions |
locale | the browser language | Locale used by the formatters |
currency | 'BRL' | Default currency of the formatters |
injectStyles | true | Injects the CSS of the interface components |
cleanAttributes | true | Strips the v-* attributes from the HTML once processed |
<script src="voodoo.full.min.js" data-manual defer></script>
<script defer>
V.config.prefix = 'data-v-';
V.config.locale = 'en-US';
V.config.currency = 'USD';
V.config.globals.formatSlug = (text) => text.toLowerCase();
V.http.setBaseURL('https://api.example.com');
V.start();
</script>
prefix, autoDiscover, root,
cleanAttributes and injectStyles change how the scan behaves. Set
them before V.start(), afterwards, what has already been processed does not go
back. The globals in V.config.globals take effect when V.start()
runs.
Script tag attributes
| Attribute | Effect |
|---|---|
data-manual | Does not start on its own. You call V.start() whenever you want |
data-defer-init | The same as data-manual |
data-prefix | Changes the attribute prefix, for instance to data-v- |
data-base-url | Base URL for V.http requests and for the HTTP directives |
data-locale | The language used by the date, number and currency formatters |
data-devtools | Turns on detailed console warnings |
data-no-styles | Does not inject the CSS of the interface components |
data-no-observer | Turns off the MutationObserver that initializes HTML created later |
data-keep-attributes | Keeps the v-* attributes in the HTML once processed |
Lifecycle events
document.addEventListener('voodoo:ready', (e) => {
console.log('Voodoo', V.version, 'started on', e.detail.root);
});
document.addEventListener('voodoo:theme', (e) => console.log(e.detail.resolved));
document.addEventListener('voodoo:palette', (e) => console.log(e.detail.colors));CSS tokens
These always exist, with a built-in default value, even without calling
V.palette():
| Token | What it is for |
|---|---|
--v-primary, --v-primary-hover, --v-primary-contrast | The main colour |
--v-accent | The highlight colour |
--v-success, --v-warning, --v-danger, --v-info | States |
--v-surface, --v-surface-2 | Backgrounds |
--v-text, --v-text-muted | Text |
--v-border | Borders |
--v-radius, --v-radius-sm | Radii |
--v-shadow | Shadow |
--v-ease | The easing curve of the transitions |
--v-z-modal, --v-z-drawer, --v-z-dropdown, --v-z-toast, --v-z-tooltip | Layers |
After V.palette(), the set grows:
| Token | What it is for |
|---|---|
--v-surface-3, --v-surface-inset | In-between backgrounds |
--v-text-soft | Text softer still |
--v-border-strong | A higher-contrast border |
--v-overlay | The darkened backdrop of the dialogs |
--v-shadow-sm, --v-shadow-lg | A smaller and a larger shadow |
--v-radius-lg, --v-radius-xl, --v-radius-full | Larger radii |
--v-focus-ring | The colour of the focus ring |
--v-font-sans, --v-font-mono | Type families |
| Scales from 50 to 900 | Shades derived from each base colour |
A prefix for strict HTML
<script src="voodoo.full.min.js" data-prefix="data-v-" defer></script>
<div data-v-data="{ n: 0 }">
<button data-v-click="n++">Add</button>
<b data-v-text="n"></b>
</div>
The library always accepts data-v-name, even when the configured prefix is a
different one. The :attribute and @event shorthands keep working in
both modes.