A Nuxt 3 module for integrating Naive UI component library into your Nuxt 3 project
- ✔️ SSR friendly
- ✔️ Auto imported and tree-shakable components & composables
- ✔️ Highly customizable for color mode and device type
- ✔️ Friendly integration with Tailwindcss
- ✔️ Implements custom components
- ✔️
NaiveNavbar
a responsive navbar for app navigation - ✔️
NaiveIcon
a wrapper based on iconify/vue with large collection of icons - ✔️
NaiveColorModeSwitch
light/dark modes switch based onuseNaiveColorMode
composable - ✔️
NaiveTabbar
a tabBar for mobile/tablet navigation
- ✔️
Add @bg-dev/nuxt-naiveui
dependency to your project
# Using npm
npm install --save-dev @bg-dev/nuxt-naiveui
# Using yarn
yarn add --dev @bg-dev/nuxt-naiveui
Add @bg-dev/nuxt-naiveui
to the modules
section of nuxt.config.ts
and define the default settings.
export default defineNuxtConfig({
modules: ["@bg-dev/nuxt-naiveui"],
naiveui: {
colorModePreference: "light",
iconSize: 18,
themeConfig: {},
},
});
That's it! You can now use @bg-dev/nuxt-naiveui
in your Nuxt app ✨
Use NaiveConfig
component in app.vue
and set themeConfig
property, alternatively set themeConfig
in the module options. The compiled themeConfig is shared globally via useNaiveTheme
composable.
<template>
<NaiveConfig :theme-config="themeConfig">
<NuxtPage></NuxtPage>
</NaiveConfig>
</template>
<script setup lang="ts">
import { ThemeConfig} from "@bg-dev/nuxt-naiveui"
const themeConfig: ThemeConfig = {
shared: {}, // Common theme options
mobileOrTablet: {}, // Theme options applied on mobile and tablet
mobile: {}, // Theme options applied on mobile only
light: {}, // Theme options applied on light mode
dark: {}, // Theme options applied on dark mode
}
</script>
You may want to force a color mode on a particular page (e.g, setting light mode on landing page). This can be achieved by setting colorMode
property in the page meta definition.
definePageMeta({
colorMode: "light",
});
Color mode integration
// tailwind.config.ts
import type { Config } from "tailwindcss";
export default <Partial<Config>>{
darkMode: "class",
};
Theme integration
// nuxt.config.ts
tailwindcss: {
exposeConfig: true;
}
// app.vue
import { ThemeConfig } from "@bg-dev/nuxt-naiveui";
import { theme } from "#tailwind-config";
const themeConfig: ThemeConfig = {
shared: {
common: {
fontFamily: theme.fontFamily.sans.join(", "),
lineHeight: theme.lineHeight.normal,
},
},
light: {
common: {
primaryColor: theme.colors.blue[600],
primaryColorHover: theme.colors.blue[500],
primaryColorPressed: theme.colors.blue[700],
},
},
dark: {
common: {
primaryColor: theme.colors.blue[500],
primaryColorHover: theme.colors.blue[400],
primaryColorPressed: theme.colors.blue[600],
},
},
};
- It's highly recommended to include
NaiveConfig
even without theme configuration as it's intended to fix global styles and accessibility issues.
Naive UI generates CSS using JS (reference), this may cause an issue on pre-rendered Nuxt pages. In fact this nuxt module proposes dynamic theming based on color mode and device type. However the pre-rendered pages are static (generated at build time). Thus a hydration mismatch may occur. Which means a flash of inaccurate styles may occur during hydration.
# Install dependencies
npm install
# Generate type stubs
npm run dev:prepare
# Develop with the playground
npm run dev
# Build the playground
npm run dev:build
# Run ESLint
npm run lint
# Run Vitest
npm run test
npm run test:watch
# Release new version
npm run release