# How to Extend or Override Existing Component Styles in Celeris Web

> Learn how to extend or override Celeris Web component styles using Tailwind utility classes, class props, CSS variables, or scoped styles for ultimate design control.

- Repository: [Kirk Lin/celeris-web](https://github.com/kirklin/celeris-web)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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.

```html
<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`](https://github.com/kirklin/celeris-web/blob/main/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.

```html
<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`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/pages/profile/index.vue) where `NCard` receives custom styling classes. Similarly, [`packages/web/components/src/Application/src/AppLogo.vue`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/packages/web/styles/src/naive-override.css) uses the `.ca-*` namespace to define component overrides:

```css
/* 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`](https://github.com/kirklin/celeris-web/blob/main/packages/web/styles/src/index.css):

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

```

```css
/* 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:

```html
<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`](https://github.com/kirklin/celeris-web/blob/main/packages/web/styles/src/naive-override.css) control theming across the application and can be redefined in custom stylesheets imported via [`index.css`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/naive-override.css) import in [`packages/web/styles/src/index.css`](https://github.com/kirklin/celeris-web/blob/main/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.