Oruga

Themes ​

Because Oruga doesn't come with any CSS by default, we would like to provide you with a variety of ready-to-use Themes. A theme provide the CSS styling for the components. They can build on existing CSS frameworks/libraries or be completely lightweight and dependency free. A theme comes as a separate package, which you can install and change completely at will. Themes that build on top of an existing CSS framework usually come with a theme-specific global Oruga Config object.

These themes are currently available:

Theme Preview

You can change the active theme for this documentation site using the dropdown menu in the navigation bar.

Using Variables ​

You can easily customise each theme at global and component level using CSS or SASS variables. Each theme has its own global and component variables, mostly of them with default values defined. The theme-specific global variables can be found on this page under Global Theme Variables. For component-specific customisation, see a component's Sass Variables section, where you'll find a complete list of all the SASS variables (with their respective default values) that you can redefine for each component (an example can be found in the Button Sass variables). Change the active theme in the navigation bar to see the theme-specific variables.

To use SASS/SCSS variables, you must use the .scss version of a theme from the package's distribution folder. For example, the Oruga theme:

js
import '@oruga-ui/theme-oruga/dist/scss/oruga.scss';

WARNING

In order to work with SASS/SCSS you might also have to install sass and sass-loader depending on your environment.

You can also use CSS variables. In most cases, any theme-specific SASS variable is converted to a CSS variable before being used.

For example to change global variable you can do:

css
:root {
  --oruga-variant-primary: green;
  --oruga-variant-danger: red;
}

or a specific component variable, such as button icon width

css
:root {
  --oruga-button-icon-width: 2.5em;
}

Oruga Theme ​

The Oruga Theme provides a ready-to-use and completely dependency-free styling.

bash
npm install @oruga-ui/theme-oruga
bash
yarn add @oruga-ui/theme-oruga
html
<link rel="stylesheet" href="https://unpkg.com/@oruga-ui/theme-oruga/dist/oruga.css" />

This theme uses the component's default class configuration and only provides a oruga.css or oruga.scss file. The stylesheet contains a full custom Oruga style for each component (the default style for this documentation).

js
import '@oruga-ui/theme-oruga/dist/oruga.css'

This can also be the best starting point for creating your own theme if you want to do a full customisation. For example to style a dropdown using override mode with oruga default stylesheet using TailwindCSS

css
.dropdown {
    @apply inline-flex relative;
}
.dropdown-menu {
    top: 100%;
    min-width: 12em;
    @apply absolute bg-white left-0 m-0 px-2 shadow-lg rounded-sm z-10;
}
.dropdown-item {
    @apply relative block no-underline px-1 py-2 cursor-pointer;
}

Take a look at the official TailwindCSS + Oruga example.

Deal with specificity ​

Oruga CSS comes with the lowest possible specifity, so you can easily override existing classes by defining new ones in the global configuration or using attributes. However, there are some cases where the specificity is higher than you might expect, for example in the Steps component the nav item contains a marker and a divider whose colors change whether the nav item is active or not.

scss
.o-steps {
    ...
    &__nav-item-active {
        .o-steps__link {
            cursor: default;
        }

        .o-steps__marker {
            @include avariable('background-color', 'steps-maker-default-color', $steps-maker-default-color);
            @include avariable('border-color', 'steps-active-color', $steps-active-color);
            @include avariable('color', 'steps-active-color', $steps-active-color);
        }

        .o-steps__divider {
            background-position: left bottom;
        }
    }

    &__nav-item-previous {
        .o-steps__marker {
            @include avariable('color', 'steps-maker-default-color', $steps-maker-default-color);
            @include avariable('background-color', 'steps-previous-color', $steps-previous-color);
        }

        .o-steps__divider {
            background-position: left bottom;
        }
    }
    ...
}

If you want to change the color you can use !important or change the values of the variables. Otherwise, you can easily increase the specificity in your stylesheet

css
.steps-nav-item-active .step-marker {
  color: blue;
  border-color: blue;
}

.steps-nav-item-active .step-divider {
  background-color: blue;
}

.steps-nav-item-previous .step-marker {
  background-color: blue;
}

.steps-nav-item-previous .step-divider {
  background-color: blue;
}

and then configure Oruga to use your custom classes

js
createApp(...)
    .use(Oruga, {
        steps: {
            itemActiveClass: 'steps-nav-item-active',
            itemPreviousClass: 'steps-nav-item-previous',
            stepMarkerClass: 'step-marker',
            stepDividerClass: 'step-divider',
        }
    });

You can see this code in action in Oruga multiframework example (code here)

Sometimes components change the way elements are positioned (horizontally, vertically...), this is another case of higher specificity. In the Steps component the vertical attribute disposes the steps vertically changing the height of the steps divider.

scss
.o-steps {
    &__wrapper-vertical {
        display: flex;
        flex-direction: row;

        .o-steps__divider {
            height: 100%;
            @include avariable('width', 'steps-divider-height', $steps-divider-height);
            top: -50%;
            left: calc(50% - #{$steps-divider-height / 2});
        }

        ...
    }
    ...
}

If you want to set the height to 50% while keeping the other attributes unchanged, you can't just define a new class (unless you want to use !important), because of the higher specificity. In this case, we suggest you define your new class like this:

css
.steps-vertical .step-divider {
  height: 50%;
}

and in your configuration

js
createApp(...)
    .use(Oruga, {
        steps: {
            verticalClass: 'steps-vertical',
            stepDividerClass: 'step-divider'
        }
    });

Bulma Theme ​

The Bulma Theme provides a customisation of the Oruga components with the Bulma CSS framework.

bash
npm install @oruga-ui/theme-bulma
bash
yarn add @oruga-ui/theme-bulma
html
<link rel="stylesheet" href="https://unpkg.com/@oruga-ui/theme-bulma/dist/bulma.css" />

The theme comes with its own Bulma-based class mapping configuration and some additional component styling that you have to import:

js
import { createApp } from 'vue'

import Oruga from '@oruga-ui/oruga-next';

import { bulmaConfig } from '@oruga-ui/theme-bulma';

import '@oruga-ui/theme-bulma/dist/bulma.css';

createApp(...)
    .use(Oruga, bulmaConfig)
    .mount('#app')

See the theme repository and the Bulma documenation for a detailed documentation.

Bootstrap Theme ​

The Bootstrap Theme provides a customisation of the Oruga components with Bootstrap.

bash
npm install @oruga-ui/theme-bootstrap
bash
yarn add @oruga-ui/theme-bootstrap
html
<link rel="stylesheet" href="https://unpkg.com/@oruga-ui/theme-bootstrap/dist/bootstrap.css" />

The theme comes with its own Bootstrap-based class mapping configuration and some additional component styling that you have to import:

js
import { createApp } from 'vue'

import Oruga from '@oruga-ui/oruga-next';

import { bootstrapConfig } from '@oruga-ui/theme-bootstrap';

import '@oruga-ui/theme-bootstrap/dist/bootstrap.css';

createApp(...)
    .use(Oruga, bootstrapConfig)
    .mount('#app')

See the theme repository and the Bootstrap documentation for a detailed documentation.

Global Theme Variables ​

INFO

You can change the active theme in the navigation bar to see the specific global variables for another theme.

Current theme ➜ Oruga

scss
// Settings
$prefix: "oruga-" !default;
$enable-host: true !default;

// Animations
$animation-speed: 150ms !default;
$animation-speed-fast: 300ms !default;
$animation-timing: ease-out !default;

// Font
$base-font-family: 
// Cross-platform generic font family (default user interface font)
    system-ui,
    // Safari for macOS and iOS (San Francisco)
    -apple-system,
    // Windows
    "Segoe UI",
    // Android
    Roboto,
    // older macOS and iOS
    "Helvetica Neue",
    // Linux
    "Noto Sans",
    "Liberation Sans",
    // Basic web fallback
    Arial,
    // Sans serif fallback
    sans-serif !default;
$base-font-size: 1rem !default;
$base-font-weight: 400 !default;
$base-line-height: 1.5 !default;

// Base Style
$base-border-radius: 4px !default;
$base-border-radius-rounded: 9999px !default;
$base-line-height: 1.5 !default;
$base-disabled-opacity: 0.5 !default;

$control-border-width: 1px !default;
$control-height: 2.25em !default;
$control-padding-vertical: calc(0.25em - #{$control-border-width});
$control-padding-horizontal: calc(1em - #{$control-border-width});
$control-box-shadow: inset 0 1px 2px hsla(0, 0%, 4%, 0.1);

// Sizes
$sizes: (
    "small": 0.75rem,
    "medium": 1.25rem,
    "large": 1.5rem,
) !default;

// Colors
$white: #ffffff !default;
$black: #000000 !default;
$grey: #7a7a7a !default;
$grey-light: #b5b5b5 !default;
$grey-lighter: #dbdbdb !default;
$grey-dark: #4a4a4a !default;

$primary: #445e00 !default;
$primary-invert: $white !default;
$secondary: #6c757d !default;
$secondary-invert: $white !default;

$success: #006724 !default;
$success-invert: $white !default;
$info: #005c98 !default;
$info-invert: $white !default;
$warning: #f4c300 !default;
$warning-invert: $black !default;
$danger: #b60000 !default;
$danger-invert: $white !default;

$colors: (
    "primary": (
        $primary,
        $primary-invert,
    ),
    "secondary": (
        $secondary,
        $secondary-invert,
    ),
    "success": (
        $success,
        $success-invert,
    ),
    "info": (
        $info,
        $info-invert,
    ),
    "warning": (
        $warning,
        $warning-invert,
    ),
    "danger": (
        $danger,
        $danger-invert,
    ),
) !default;

See ➜ 📄 SCSS files

Current theme ➜ Bulma

scss
// This file is home to defaulted variables which DO reference bulma but are not part of a particular component


$sizes-map: (
    "small": dv.$size-small,
    "normal": dv.$size-normal,
    "medium": dv.$size-medium,
    "large": dv.$size-large,
) !default;
// This file is home to defaulted variables which need to be passed to Bulma, or to general defaulted variables which are not part of a particular component


// adds :root variables also as :host
$enable-host: true !default;

$speed-slow: 150ms !default;
$speed-slower: 250ms !default;

// oruga defines an extra secondary color
$secondary: #6c757d !default;

// alternative to focus-shadow-size
$active-shadow-size: 0 0 0.5em !default;

$theme-bulma-custom-colors: () !default;

// Merge any user-defined custom colors with the custom colors defined by the theme. This will be passes to Bulma as $custom-colors
// This is the one variable in this file which is not defaulted, but it collects defaulted values so it counts. It's going to be passed into bulma so it has to be here so it comes first
// merge our custom-colors with the overridable map
$theme-bulma-custom-colors-merged: map.merge(
    (
        "secondary": $secondary,
    ),
    $theme-bulma-custom-colors
);

See ➜ 📄 SCSS files

Current theme ➜ Bootstrap

scss
// adds :root variables also as :host
$enable-host: true !default;

$speed-slow: 150ms !default;
$speed-slower: 250ms !default;
$easing: ease !default;

// sizes variants
$sizes: (
    "x-small": 0.5rem,
    "small": 0.75rem,
    "medium": 1.25rem,
    "large": 1.5rem,
    "x-large": 2rem,
) !default;

// adding aditional gray-light color to colors map
$custom-colors: (
    "gray-light": $gray-300,
);
$colors: map.merge($colors, $custom-colors);

// these theme color maps are available:
// - $theme-colors                -> var(--#{$prefix}#{$name});
// - $theme-colors-contrast       -> var(--#{$prefix}#{$name}-contrast);
// - $theme-colors-text           -> var(--#{$prefix}#{$name}-text-emphasis);
// - $theme-colors-rgb            -> var(--#{$prefix}#{$name}-rgb);
// - $theme-colors-bg-subtle      -> var(--#{$prefix}#{$name}-bg-subtle)
// - $theme-colors-border-subtle  -> var(--#{$prefix}#{$name}-border-subtle)

See ➜ 📄 SCSS files

Released under the MIT License.

Copyright © 2020-2025 Walter Tommasi