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 drop down 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 to 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'
        }
    });

In the Oruga documentation you'll find a special note (🔍) in the Class Prop Inspector for classes with a higher specificity.

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 ➜ Bulma

scss
$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;

// make the custom colors extandable by providing a new variable to override
$custom-colors: () !default;

@forward "bulma/sass/utilities/derived-variables" with (
    // adding aditional colors to colors map
    $custom-colors:
        map.merge(
            // merge our custom-colors with the overridable map
            ("secondary": $secondary),
            $custom-colors
        )
);


$sizes-map: (
    "small": vars.$size-small,
    "normal": vars.$size-normal,
    "medium": vars.$size-medium,
    "large": vars.$size-large,
) !default;

See ➜ 📄 SCSS files

Current theme ➜ Bootstrap

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

// Sizes
$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-2024 Walter Tommasi