N Global Style

Naive UI Global Style Component

Global Style is a utility component that synchronizes common global styles from n-config-provider to document.body. It ensures the body element matches the theme settings.

When to Use

Use this component when:

• Body background sync: Apply theme background color to the entire page
• Global font family: Sync font settings to document body
• Theme consistency: Ensure the whole page reflects the current theme
• Dark mode support: Automatically update body styles for dark/light themes

When to Invoke

Invoke this skill when:

• User needs to apply theme background to the whole page
• User wants the body to change with theme switching
• User asks about global styling for the application
• User needs to sync theme styles outside of n-config-provider
• User wants to ensure consistent theming across the entire page

Features

• Body Style Sync: Automatically syncs theme styles to document.body
• Background Color: Updates body background with theme
• Font Family: Applies theme font settings globally
• Theme Reactive: Updates automatically when theme changes
• Zero Configuration: Works out of the box with n-config-provider

Basic Usage

Basic Global Style

<template>
  <n-config-provider :theme="theme">
    <n-global-style />
    <n-card>
      <n-space>
        <n-button @click="theme = darkTheme">Dark</n-button>
        <n-button @click="theme = null">Light</n-button>
      </n-space>
      <p>The body background will change with the theme.</p>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)
</script>

With Theme Overrides

<template>
  <n-config-provider
    :theme="theme"
    :theme-overrides="themeOverrides"
  >
    <n-global-style />
    <n-card>
      <n-button type="primary">Primary Button</n-button>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)

const themeOverrides = {
  common: {
    bodyColor: '#f5f5f5'
  }
}
</script>

Common Patterns

Complete Application Setup

<template>
  <n-config-provider
    :theme="theme"
    :theme-overrides="themeOverrides"
    :locale="locale"
    :date-locale="dateLocale"
  >
    <n-global-style />
    <n-message-provider>
      <n-dialog-provider>
        <n-notification-provider>
          <n-loading-bar-provider>
            <router-view />
          </n-loading-bar-provider>
        </n-notification-provider>
      </n-dialog-provider>
    </n-message-provider>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme, zhCN, dateZhCN } from 'naive-ui'

const theme = ref(null)
const locale = ref(zhCN)
const dateLocale = ref(dateZhCN)

const themeOverrides = {
  common: {
    primaryColor: '#18A058'
  }
}
</script>

Theme Toggle with Persistence

<template>
  <n-config-provider :theme="theme">
    <n-global-style />
    <n-layout>
      <n-layout-header>
        <n-switch
          :value="isDark"
          @update:value="toggleTheme"
        >
          <template #checked>
            <n-icon><MoonIcon /></n-icon>
          </template>
          <template #unchecked>
            <n-icon><SunIcon /></n-icon>
          </template>
        </n-switch>
      </n-layout-header>
      <n-layout-content>
        <router-view />
      </n-layout-content>
    </n-layout>
  </n-config-provider>
</template>

<script setup>
import { ref, computed, onMounted } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)

const isDark = computed(() => theme.value === darkTheme)

const toggleTheme = (value) => {
  theme.value = value ? darkTheme : null
  localStorage.setItem('theme', value ? 'dark' : 'light')
}

onMounted(() => {
  const savedTheme = localStorage.getItem('theme')
  if (savedTheme === 'dark') {
    theme.value = darkTheme
  }
})
</script>

Follow System Theme

<template>
  <n-config-provider :theme="theme">
    <n-global-style />
    <n-card>
      <p>Following system theme: {{ osTheme }}</p>
      <n-button @click="toggleFollowSystem">
        {{ followSystem ? 'Stop Following System' : 'Follow System' }}
      </n-button>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { ref, computed, watch } from 'vue'
import { useOsTheme, darkTheme } from 'naive-ui'

const osTheme = useOsTheme()
const followSystem = ref(true)
const manualTheme = ref(null)

const theme = computed(() => {
  if (!followSystem.value) {
    return manualTheme.value
  }
  return osTheme.value === 'dark' ? darkTheme : null
})

const toggleFollowSystem = () => {
  followSystem.value = !followSystem.value
}
</script>

With Preflight Style Disabled

<template>
  <n-config-provider
    :theme="theme"
    preflight-style-disabled
  >
    <n-global-style />
    <n-card>
      <p>
        Preflight styles are disabled, but n-global-style
        will still sync theme styles to body.
      </p>
    </n-card>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)
</script>

Multiple Config Providers

<template>
  <n-config-provider :theme="theme">
    <n-global-style />
    <n-layout>
      <n-layout-sider>
        <n-config-provider :theme="darkTheme" abstract>
          <n-menu :options="menuOptions" />
        </n-config-provider>
      </n-layout-sider>
      <n-layout-content>
        <router-view />
      </n-layout-content>
    </n-layout>
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)
</script>

Best Practices

1. Place inside n-config-provider: Always place n-global-style inside n-config-provider

   <n-config-provider :theme="theme">
     <n-global-style />
     <App />
   </n-config-provider>
   

2. Single instance: Only one n-global-style is needed per application

   <n-config-provider>
     <n-global-style />
     <n-message-provider>
       <App />
     </n-message-provider>
   </n-config-provider>
   

3. Combine with theme persistence: Store theme preference in localStorage

   onMounted(() => {
     const savedTheme = localStorage.getItem('theme')
     if (savedTheme === 'dark') {
       theme.value = darkTheme
     }
   })
   

4. Use with preflight-style-disabled: When you disable preflight styles, n-global-style provides reactive global styles

   <n-config-provider preflight-style-disabled>
     <n-global-style />
   </n-config-provider>
   

5. Position in component tree: Place at the root level after n-config-provider

   <n-config-provider>
     <n-global-style />
     <n-message-provider>
       <n-dialog-provider>
         <App />
       </n-dialog-provider>
     </n-message-provider>
   </n-config-provider>
   

6. No props needed: The component works without any configuration

   <n-global-style />
   

7. Styles applied: The component syncs these styles to body:

   • Background color (bodyColor from theme)
   • Font family (fontFamily from theme)
   • Text color
   • Other global theme variables

8. Why use it: Without n-global-style, the body won't automatically update when theme changes, leading to visual inconsistency