Installation
Adding Windi UI
to your project is relatively straightforward. Run one of the following commands in your terminal to get started:
pnpm add windi-vue
pnpm add windi-vue
yarn add windi-vue
yarn add windi-vue
npm install windi-vue
npm install windi-vue
Usage
- Add the Windi UI theme file in your tailwind.config.cjs file as shown below:
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}", "node_modules/windi-vue/dist/theme/*.{js,jsx,ts,tsx,vue}"],
darkMode: "class",
theme: {
extend: {},
},
plugins: [],
};
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}", "node_modules/windi-vue/dist/theme/*.{js,jsx,ts,tsx,vue}"],
darkMode: "class",
theme: {
extend: {},
},
plugins: [],
};
Component registration
With Windi UI, you have the flexibility to register components precisely as you wish:
Import All Components
To import all the components provided by Windi UI
, add WindiUI
in your main entry file as shown below:
import { createApp } from 'vue'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import WindiUI from 'windi-vue'
const app = createApp(App)
app.use(WindiUI, windiTheme)
app.mount('#app')
import { createApp } from 'vue'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import WindiUI from 'windi-vue'
const app = createApp(App)
app.use(WindiUI, windiTheme)
app.mount('#app')
DANGER
Be warned. By doing this, you are importing all the components that are provided by Windi UI and in your final bundle all the components including the ones you didn't use will be bundled.
Individual Components with Tree Shaking
Probably you might not want to globally register all the components but instead only import the components that you need. You can achieve this by doing the following:
- Import the
createWindiUI
option as well as the components you need as shown below:
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import { WKbd, createWindiUI } from 'windi-vue'
import WindiUI from 'windi-vue'
const app = createApp(App)
const UI = createWindiUI({
prefix: 'T',
components: [WKbd],
})
app.use(UI, windiTheme)
app.use(WindiUI, windiTheme)
app.mount('#app')
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import { WKbd, createWindiUI } from 'windi-vue'
import WindiUI from 'windi-vue'
const app = createApp(App)
const UI = createWindiUI({
prefix: 'T',
components: [WKbd],
})
app.use(UI, windiTheme)
app.use(WindiUI, windiTheme)
app.mount('#app')
- Now you can use the component as shown below:
<template>
<div>
<TKbd>K</TKbd>
</div>
</template>
<template>
<div>
<TKbd>K</TKbd>
</div>
</template>
TIP
The prefix
option is only available for individual component imports.
Auto Imports with Tree Shaking
Windi UI comes with an intelligent resolver that automatically imports only used components.
This is made possible by leveraging a tool known as unplugin-vue-components which lets you auto import components on demand thus omitting import statements and still get the benefits of tree shaking.
To achieve this you need to do the following:
- Install the
unplugin-vue-components
package by running one of the following commands:
pnpm add -D unplugin-vue-components
pnpm add -D unplugin-vue-components
yarn add -D unplugin-vue-components
yarn add -D unplugin-vue-components
npm i -D unplugin-vue-components
npm i -D unplugin-vue-components
- Head over to your
main.ts
ormain.js
file and setregisterComponents
tofalse
as shown below:
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import { WKbd, createWindiUI } from 'windi-vue'
import { createWindiUI } from 'windi-vue'
import WindiUI from 'windi-vue'
const app = createApp(App)
const UI = createWindiUI({
prefix: 'T',
components: [WKbd],
})
const UI = createWindiUI({
registerComponents: false
})
app.use(UI, windiTheme)
app.use(WindiUI, windiTheme)
app.mount('#app')
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import { WKbd, createWindiUI } from 'windi-vue'
import { createWindiUI } from 'windi-vue'
import WindiUI from 'windi-vue'
const app = createApp(App)
const UI = createWindiUI({
prefix: 'T',
components: [WKbd],
})
const UI = createWindiUI({
registerComponents: false
})
app.use(UI, windiTheme)
app.use(WindiUI, windiTheme)
app.mount('#app')
- Head over to your
vite.config.ts
orvite.config.js
file and add the following:
// other imports
import { WindiUIComponentResolver } from 'windi-vue'
import Components from "unplugin-vue-components/vite"
export default defineConfig({
plugins: [
// other plugins
Components({
resolvers: [
WindiUIComponentResolver()
]
}),
],
})
// other imports
import { WindiUIComponentResolver } from 'windi-vue'
import Components from "unplugin-vue-components/vite"
export default defineConfig({
plugins: [
// other plugins
Components({
resolvers: [
WindiUIComponentResolver()
]
}),
],
})
- Now you can simply use any component that you want and it will be auto imported on demand ✨
<template>
<div>
<WKbd>K</WKbd>
</div>
</template>
<template>
<div>
<WKbd>K</WKbd>
</div>
</template>
Troubleshooting TypeScript Error
If you're encountering the TypeScript error: Cannot find module 'windi-vue/dist/theme/windiTheme' or its corresponding type declarations, you can follow these steps to resolve it:
- Create a
windi-vue.d.ts
declaration file in yoursrc
directory and inside it paste the following code:
declare module 'windi-vue/dist/theme/windiTheme'
declare module 'windi-vue/dist/theme/windiTheme'
The error should now be resolved.
This issue is set to be fixed in the next release of Windi UI v0.0.1 Alpha
🥳 Well done, you can now go ahead and build your web application with ease.