Vue UI Components Documentation
A jQWidgets theme is a stylesheet and a name. The stylesheet jqx.fluent.css styles every widget whose theme is fluent: the widget adds the name to its CSS classes, such as jqx-grid-fluent, and the stylesheet's rules match those classes. In Vue you import the stylesheet in src/main.ts and set the theme prop of each component.
This guide does that in a Vite project with Vue 3.5 and jqwidgets-scripts 27.0.1. It then switches between a light and a dark theme while the app runs, and follows the dark mode of the operating system. The project setup is described in Vite and Vue 3 with <script setup>. The theme list below is for 27.1.0, the current release. The notes that name 27.0.1 describe that version, and say where 27.1.0 changed it.
jqwidgets-scripts installs the stylesheets in node_modules/jqwidgets-scripts/jqwidgets/styles/. jqx.base.css holds the layout rules every widget needs and is always loaded first. Each other jqx.*.css file is one theme, and the theme's name is the file name without jqx. and .css.
| Kind | Theme names in jqwidgets-scripts 27.1.0 |
|---|---|
| Design systems | fluent, fluent-dark, material, material-dark, material-green, material-green-dark, material-purple, material-purple-dark, tailwind, tailwind-dark, tailwind-blue, tailwind-blue-dark, bootstrap |
| Light and dark pairs | fluent and fluent-dark, material and material-dark, material-green and material-green-dark, material-purple and material-purple-dark, tailwind and tailwind-dark, tailwind-blue and tailwind-blue-dark, light and dark, metro and metrodark, ui-lightness and ui-darkness |
| Other dark themes | black, android, blue, windowsphone, ui-le-frog |
| Other light themes | arctic, blackberry, classic, darkblue, energyblue, flat, fresh, glacier, highcontrast, mobile, office, orange, shinyblack, summer, web, ui-overcast, ui-redmond, ui-smoothness, ui-start, ui-sunny |
| Legacy files | jqx.light-ie.css and jqx.dark-ie.css (theme names light and dark), jqx.fluent_old.css (theme name fluent) |
Version 27.1.0 added fluent-dark, material-dark, material-green-dark and material-purple-dark, and the tailwind-blue pair: Tailwind with the blue of Microsoft 365. Each dark theme has the same sizes and spacing as its light theme, so nothing moves when the app switches between them. Version 27.0.1 has none of them; there, use tailwind-dark for a dark look.
The legacy files are for existing pages. jqx.light-ie.css and jqx.dark-ie.css are light and dark written without CSS variables. jqx.fluent_old.css is an earlier version of fluent with the same class names, so load one or the other. The folder also holds theme.css, a template for a theme of your own named theme.
Import the base stylesheet and the theme in src/main.ts, in this order:
import { createApp } from 'vue';
import 'jqwidgets-scripts/jqwidgets/styles/jqx.base.css';
import 'jqwidgets-scripts/jqwidgets/styles/jqx.fluent.css';
import App from './App.vue';
createApp(App).mount('#app');
The theme has to come after jqx.base.css: both stylesheets style the same elements, and the later one wins. Vite bundles the CSS files with the images and fonts they refer to.
Vite needs two additions to vite.config.ts for jqWidgets 27.0.1. With 27.1.0 the dev server runs without the plugin, and only the legacy jqx.light-ie.css and jqx.dark-ie.css still need errorRecovery; both settings are harmless there.
import vue from '@vitejs/plugin-vue';
import { defineConfig, type Plugin } from 'vite';
// jqwidgets-scripts 27.0.1: globalize.js, which the Grid component imports, hands its code
// `this` as the window. In an ES module `this` is undefined, and the dev server serves the file
// as one, so `npm run dev` stops with "Cannot set properties of undefined (setting 'Globalize')".
// (The production build is not affected.) This passes the window instead.
const globalizeWindow: Plugin = {
name: 'jqwidgets-globalize-window',
transform(code, id) {
if (id.includes('jqwidgets-scripts/jqwidgets/globalization/globalize.js')) {
return code.replace(/\}\(this\)\);/, '}(window));');
}
}
};
export default defineConfig({
plugins: [vue(), globalizeWindow],
// Some jqWidgets themes still contain Internet Explorer CSS hacks (*zoom: 1), which Vite's
// CSS minifier rejects: errorRecovery drops those lines instead of stopping the build.
css: { lightningcss: { errorRecovery: true } },
});
css.lightningcss.errorRecovery keeps npm run build from stopping with Unexpected token Semicolon. Several themes, material and light among them, still contain Internet Explorer hacks such as *zoom: 1; fluent, tailwind and tailwind-dark do not, but the setting does no harm.npm run dev as soon as a Grid, Calendar, DateTimeInput, Form or Scheduler is on the page. Add a Grid to a Vue 3 app explains it.Every jQWidgets Vue component has a theme prop. Give it the theme's name:
src/App.vue:
<script setup lang="ts">
import JqxGrid from 'jqwidgets-scripts/jqwidgets-vue3/vue_jqxgrid.vue';
// Defined globally by the jQWidgets core, which the Grid component imports.
declare const jqx: any;
const source = new jqx.dataAdapter({
localdata: [
{ name: 'Espresso', category: 'Coffee', price: 2.2, stock: 140 },
{ name: 'Cappuccino', category: 'Coffee', price: 3.1, stock: 85 },
{ name: 'Flat White', category: 'Coffee', price: 3.4, stock: 62 },
{ name: 'Green Tea', category: 'Tea', price: 2.5, stock: 120 },
{ name: 'Chai Latte', category: 'Tea', price: 3.6, stock: 40 },
{ name: 'Hot Chocolate', category: 'Chocolate', price: 3.2, stock: 75 },
{ name: 'Croissant', category: 'Bakery', price: 2.4, stock: 30 },
{ name: 'Blueberry Muffin', category: 'Bakery', price: 2.9, stock: 18 }
],
datatype: 'array',
datafields: [
{ name: 'name', type: 'string' },
{ name: 'category', type: 'string' },
{ name: 'price', type: 'number' },
{ name: 'stock', type: 'number' }
]
});
const columns = [
{ text: 'Product', datafield: 'name' },
{ text: 'Category', datafield: 'category', width: 130 },
{ text: 'Price', datafield: 'price', width: 90, cellsformat: 'c2', cellsalign: 'right', align: 'right' },
{ text: 'In stock', datafield: 'stock', width: 90, cellsalign: 'right', align: 'right' }
];
</script>
<template>
<JqxGrid
theme="fluent"
:width="560"
:autoheight="true"
:sortable="true"
:source="source"
:columns="columns"
/>
</template>
theme="fluent" passes a fixed string; :theme="name" passes the value of an expression. Each component needs its own theme; a widget without one uses only jqx.base.css.
To let users change the theme, the app needs two things: the new theme's stylesheet on the page, and the new name in every component's theme. A composable can do both, keeping the name in a ref that the components read.
An import with ?url gives the address of a stylesheet without adding it to the page. Vite still processes the file: npm run build writes it to dist/assets/ with a hash in its name, together with the images and fonts it refers to. During npm run dev the address points to the file in node_modules.
Several themes, such as fluent, tailwind, tailwind-dark, light and dark, set CSS variables with the same names on :root. If two of them are on the page, the one loaded last decides the colours of both: after tailwind-dark has been loaded, a fluent grid turns dark. So the composable adds the new theme's <link>, waits until it has loaded, and then removes the previous one.
src/useTheme.ts:
import { readonly, ref } from 'vue';
// ?url: Vite writes each theme to a file of its own and returns its URL, without adding it to the page.
import fluent from 'jqwidgets-scripts/jqwidgets/styles/jqx.fluent.css?url';
import tailwind from 'jqwidgets-scripts/jqwidgets/styles/jqx.tailwind.css?url';
import tailwindDark from 'jqwidgets-scripts/jqwidgets/styles/jqx.tailwind-dark.css?url';
const urls: Record<string, string> = { fluent, tailwind, 'tailwind-dark': tailwindDark };
// What the picker offers: 'system' follows the dark mode of the operating system or browser.
export const choices = ['system', ...Object.keys(urls)];
const darkMode = window.matchMedia('(prefers-color-scheme: dark)');
const choice = ref('system');
const theme = ref('');
let current: HTMLLinkElement | undefined;
let latest: HTMLLinkElement | undefined;
async function load(name: string): Promise<void> {
const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = urls[name];
latest = link;
await new Promise<void>((resolve, reject) => {
link.onload = () => resolve();
link.onerror = () => {
link.remove();
reject(new Error(`${link.href} could not be loaded`));
};
document.head.appendChild(link);
});
// A later choice was made while this one loaded: keep that one.
if (link !== latest) {
link.remove();
return;
}
// A theme stylesheet sets CSS variables on :root, so keep only one on the page.
current?.remove();
current = link;
theme.value = name;
document.body.classList.toggle('dark', name.endsWith('-dark'));
}
function choose(value: string): Promise<void> {
choice.value = value;
return load(value === 'system' ? (darkMode.matches ? 'tailwind-dark' : 'fluent') : value);
}
// Follow the operating system when it switches between light and dark mode.
darkMode.addEventListener('change', () => {
if (choice.value === 'system') {
choose('system');
}
});
export function useTheme() {
return { choice: readonly(choice), theme: readonly(theme), choose };
}
The theme ref changes only after the stylesheet has loaded, so the widgets never show the new theme's classes without its rules. If the user picks another theme while one is still loading, the later choice wins. The dark class on <body> lets the page itself follow the theme, as shown below.
The state lives in the module, outside the function, so every component that calls useTheme() shares the same theme. src/main.ts loads the first theme before it mounts the app:
import { createApp } from 'vue';
import 'jqwidgets-scripts/jqwidgets/styles/jqx.base.css';
import './style.css';
import App from './App.vue';
import { useTheme } from './useTheme';
// Load the first theme before the app renders.
useTheme().choose('system').then(() => createApp(App).mount('#app'));
jqx.base.css is part of the bundle, and the composable adds the theme's <link> at the end of <head>, so the theme comes after it.
src/App.vue:
<script setup lang="ts">
import { ref, watch } from 'vue';
import JqxButton from 'jqwidgets-scripts/jqwidgets-vue3/vue_jqxbuttons.vue';
import JqxDropDownList from 'jqwidgets-scripts/jqwidgets-vue3/vue_jqxdropdownlist.vue';
import JqxGrid from 'jqwidgets-scripts/jqwidgets-vue3/vue_jqxgrid.vue';
import { choices, useTheme } from './useTheme';
// Defined globally by the jQWidgets core, which the Grid component imports.
declare const jqx: any;
// The method of the Grid and DropDownList components that this component calls.
interface Widget {
setOptions: (options: object) => void;
}
const { choice, theme, choose } = useTheme();
// The Grid and the DropDownList get the theme the app started with as a fixed prop, and every
// later theme through setOptions: a changed prop would reset them (jqwidgets-scripts 27.0.1).
const startTheme = theme.value;
const grid = ref<Widget | null>(null);
const sizeList = ref<Widget | null>(null);
watch(theme, (name) => {
grid.value?.setOptions({ theme: name });
sizeList.value?.setOptions({ theme: name });
});
const source = new jqx.dataAdapter({
localdata: [
{ name: 'Espresso', category: 'Coffee', price: 2.2, stock: 140 },
{ name: 'Cappuccino', category: 'Coffee', price: 3.1, stock: 85 },
{ name: 'Flat White', category: 'Coffee', price: 3.4, stock: 62 },
{ name: 'Green Tea', category: 'Tea', price: 2.5, stock: 120 },
{ name: 'Chai Latte', category: 'Tea', price: 3.6, stock: 40 },
{ name: 'Hot Chocolate', category: 'Chocolate', price: 3.2, stock: 75 },
{ name: 'Croissant', category: 'Bakery', price: 2.4, stock: 30 },
{ name: 'Blueberry Muffin', category: 'Bakery', price: 2.9, stock: 18 }
],
datatype: 'array',
datafields: [
{ name: 'name', type: 'string' },
{ name: 'category', type: 'string' },
{ name: 'price', type: 'number' },
{ name: 'stock', type: 'number' }
]
});
const columns = [
{ text: 'Product', datafield: 'name' },
{ text: 'Category', datafield: 'category', width: 130 },
{ text: 'Price', datafield: 'price', width: 90, cellsformat: 'c2', cellsalign: 'right', align: 'right' },
{ text: 'In stock', datafield: 'stock', width: 90, cellsalign: 'right', align: 'right' }
];
const sizes = ['Small', 'Medium', 'Large'];
</script>
<template>
<label class="toolbar">
Theme
<select :value="choice" @change="choose(($event.target as HTMLSelectElement).value)">
<option v-for="name in choices" :key="name" :value="name">{{ name }}</option>
</select>
</label>
<JqxGrid
ref="grid"
:theme="startTheme"
:width="560"
:autoheight="true"
:sortable="true"
:source="source"
:columns="columns"
/>
<div class="toolbar">
<JqxDropDownList ref="sizeList" :theme="startTheme" :source="sizes" :selectedIndex="1" :width="200" :height="32" />
<JqxButton :theme="theme" :width="120" :height="32">Order</JqxButton>
</div>
</template>
<style scoped>
.toolbar {
display: flex;
align-items: center;
gap: 0.75rem;
margin: 1.5rem 0;
}
select {
font: inherit;
padding: 0.25rem 0.5rem;
}
</style>
The button's :theme is bound to the ref: when the ref changes, Vue passes the new name and the button draws itself again with the new classes. The Grid and the DropDownList start with the same theme, but they get later ones from the watch, through their setOptions method; the next section explains why. The picker is a native <select> whose change event calls choose.
The system choice follows the dark mode of the operating system or browser. matchMedia('(prefers-color-scheme: dark)') says whether dark mode is on, and its change event fires when the user switches it. The composable then picks tailwind-dark or fluent:
function choose(value: string): Promise<void> {
choice.value = value;
return load(value === 'system' ? (darkMode.matches ? 'tailwind-dark' : 'fluent') : value);
}
// Follow the operating system when it switches between light and dark mode.
darkMode.addEventListener('change', () => {
if (choice.value === 'system') {
choose('system');
}
});
A theme the user picked stays, whatever the system does. If your site has a dark mode switch of its own, call choose('tailwind-dark') and choose('fluent') from it instead.
A theme styles the widgets, not the page around them. src/style.css, imported in src/main.ts, gives the page dark colours when the composable sets the dark class; color-scheme makes the browser draw native controls, such as the <select>, dark as well:
body {
margin: 24px;
font-family: system-ui, sans-serif;
color-scheme: light;
background: #ffffff;
color: #1f2937;
}
body.dark {
color-scheme: dark;
background: #14171c;
color: #e5e7eb;
}
In jqwidgets-scripts 27.0.1, a Vue component re-renders when one of its props changes, and then applies all of its props to the widget again, not only the one that changed. For JqxButton that is harmless. With :theme="theme" on the other two components of the example, a theme change did this:
source again and stayed on Loading...: in tailwind-dark its rows were gone, and after the next change the rows came back under the Loading... box.selectedIndex again: after the user picked Large, a new theme put it back to Medium.In 27.1.0 a component applies only the props whose value changed, so a theme change no longer resets the grid or the list. With 27.0.1, give such a component a theme that does not change, and set each new theme with setOptions, which changes only that option:
const startTheme = theme.value;
const grid = ref<Widget | null>(null);
const sizeList = ref<Widget | null>(null);
watch(theme, (name) => {
grid.value?.setOptions({ theme: name });
sizeList.value?.setOptions({ theme: name });
});
Props that never change do not re-render the component, so the grid keeps its rows, sort and selection, and the list its selected item. The same holds for every other prop of the grid; Sorting, filtering and paging from Vue shows more.
jqx.base.css applies. Check that the theme is imported (or loaded by the composable) and that the name matches the file: jqx.tailwind-dark.css is tailwind-dark. There is no fluent-dark in 27.0.1; 27.1.0 has it.jqx.base.css is loaded after the theme. Import it first.<link> when you load the next one.selectedIndex. The component's props changed; see When a component loses its state.npm run dev stops with "Cannot set properties of undefined (setting 'Globalize')". Add the plugin shown in Add a theme.npm run build fails with "[lightningcss minify] Unexpected token Semicolon". Add css: { lightningcss: { errorRecovery: true } } to vite.config.ts.npm run build warns that some chunks are larger than 500 kB. The chunk with the Grid is about 1.5 MB (390 kB compressed). The build still succeeds; raise build.chunkSizeWarningLimit to silence the warning.cursor as a Boolean with the default 'pointer'. Vue checks props only in development, and the button works. In 27.1.0 cursor is a string.More: Vite and Vue 3 with <script setup>, Add a Grid to a Vue 3 app, and the Vue Grid tutorials. Live examples of every Vue component: jqwidgets.com/vue.