How to Extend or Override Existing Component Styles in Celeris Web

You can extend or override existing component styles in Celeris Web using Tailwind utility classes, component-level class props, global CSS variable overrides in the .ca-* namespace, or scoped component styles.

Celeris Web is a Vue-based admin template that combines Naive UI components with Tailwind CSS utilities. Because the framework exposes styling hooks through CSS custom properties and specific class namespaces, you can customize any component's appearance without modifying the library source code.

Method 1: Apply Tailwind Utility Classes

The simplest way to override styles is to pass Tailwind utility classes directly to any Naive UI component via the class attribute. Tailwind's JIT compiler generates the necessary CSS at build time.

<NButton
  class="bg-primary-600 hover:bg-primary-700 text-white"
  type="primary"
>
  Save
</NButton>

Most Naive UI components forward the class prop to their root element, allowing utility classes to override default styling through specificity. You can see this pattern in apps/admin/src/pages/login/components/AuthForm/index.vue where components receive utility classes like class="auth-form-wrap w-full".

Method 2: Use Component-Level Class and Style Props

For targeted overrides, supply a custom class to components that accept class and style props. This approach lets you write selectors that are more specific than the default library rules.

<NCard class="rounded-xl shadow-lg border-2 border-primary-300">
  <!-- custom card content -->
</NCard>

The NCard component forwards the class to its root <div class="n-card …">, ensuring your utilities take precedence. This technique is demonstrated in apps/admin/src/pages/profile/index.vue where NCard receives custom styling classes. Similarly, packages/web/components/src/Application/src/AppLogo.vue accepts class and style props to allow callers to override logo size or color.

Method 3: Override Global CSS and CSS Variables

Celeris Web defines a "naive-override" stylesheet that sets CSS variables and base rules for Naive UI components. You can modify these globally by editing or extending the files in packages/web/styles/src/.

The .ca-* Namespace and naive-override.css

The base stylesheet packages/web/styles/src/naive-override.css uses the .ca-* namespace to define component overrides:

/* packages/web/styles/src/naive-override.css */
.ca-modal {
  background-color: rgba(var(--modal-color-rgb), 0.75);
  backdrop-filter: blur(20px);
}
.ca-drawer--right-placement {
  border-top-left-radius: var(--border-radius);
  border-bottom-left-radius: var(--border-radius);
}

Redefining CSS Variables Globally

To change variables across the entire application, create a new stylesheet and import it after the base file in packages/web/styles/src/index.css:

/* packages/web/styles/src/my-overrides.css */
:root {
  --modal-color-rgb: 30 30 30;  /* dark gray */
  --border-radius: 0.5rem;
}

/* packages/web/styles/src/index.css */
@import "./naive-override.css";
@import "./my-overrides.css";   /* <- overrides go after the base file */

Import order matters—files loaded later win when specificity is equal.

Method 4: Scoped Component Styles

For one-off adjustments, add a <style scoped> block within a .vue file and target specific class names:

<template>
  <NButton class="custom-btn">Click me</NButton>
</template>

<style scoped>
.custom-btn {
  @apply bg-green-500 hover:bg-green-600;
}
</style>

This keeps overrides encapsulated to the component while still leveraging Tailwind's @apply directive for consistency.

Summary

• Tailwind utilities provide the fastest way to tweak individual component instances by passing classes directly to Naive UI components.
• Component props like class and style are forwarded to root elements, allowing custom classes to override defaults through higher specificity.
• Global CSS variables defined in packages/web/styles/src/naive-override.css control theming across the application and can be redefined in custom stylesheets imported via index.css.
• Scoped styles in .vue files offer isolated overrides for specific pages or components without affecting the global stylesheet.

Frequently Asked Questions

Can I override Naive UI component styles without modifying the library source code?

Yes. Celeris Web is designed to be customized via the .ca-* namespace and CSS custom properties. By adding your own stylesheets to packages/web/styles/src/ and importing them in index.css, you can override any default Naive UI appearance without touching node_modules.

Where are the base CSS variables defined in Celeris Web?

Base CSS variables and component overrides reside in packages/web/styles/src/naive-override.css. This file defines variables like --modal-color-rgb and --border-radius, plus specific selectors for components such as .ca-modal and .ca-drawer--right-placement.

How do I ensure my custom styles override the default ones?

Load your custom stylesheets after the base naive-override.css import in packages/web/styles/src/index.css. CSS cascades based on import order when specificity is identical, so placing your imports last ensures your rules take precedence. For component-level overrides, using the class prop automatically adds specificity since the class is applied directly to the rendered element.

Can I use Tailwind's @apply directive in scoped styles?

Yes. You can use @apply within <style scoped> blocks in Vue single-file components to reuse Tailwind utilities while keeping the styles encapsulated. This is particularly useful for creating semantic class names that bundle multiple utility classes together for specific component variants.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}