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

INFO

For the Oruga Theme, you have to import the oruga-full.css stylesheet to use CSS variables.

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 default Oruga Theme provides some ready-to-use and completely dependency-free styling and comes with two different versions, oruga.css and oruga-full.css. This theme uses the component's default class configuration.

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" />

  • The minimal oruga.css provides a lightweight stylesheet that contains only minimal and essential CSS rules for Oruga components such as display, position, z-index and other basic attributes. This could be the best starting point for creating your own theme if you want to do a full customisation.

  • The oruga-full.css stylesheet provides the full custom Oruga style for each component (the default style for this documentation).

For more info read "Differences between default and full css" or go to "Customisation" if you want to know more about components customisation.

INFO

If you use the base stylesheet to browse the documentation, some examples won't work as you expect because sizes, variants and decorations are not included in the minimal Oruga stylesheet.

Differences between default and full css ​

The default stylesheet contains only the essantial rules for Oruga components such as display, position, z-index and other basic attributes.

For example to style a dropdown using override mode with oruga default stylesheet using TailwindCSS

js
import '@oruga-ui/theme-oruga/dist/oruga.css'
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;
}

And here's how to style a dropdown using oruga-full stylesheet

js
import '@oruga-ui/theme-oruga/dist/oruga-full.css'
css
.dropdown-menu {
    min-width: 12em;
    @apply bg-white m-0 px-2 shadow-lg rounded-sm z-10;
}
.dropdown-item {
    @apply 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 ➜ Oruga Base

scss
// Settings
$whitelist: () !default;
$css-vars: true !default;
$prefix: "oruga-" !default;

// Animations
$speed: 300ms !default;
$speed-slow: 150ms !default;
$speed-slower: 250ms !default;
$easing: 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-rounded-border-radius: 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.375em - #{$control-border-width});
$control-padding-horizontal: calc(0.625em - #{$control-border-width});

// 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 ➜ Oruga Full

scss
// Settings
$whitelist: () !default;
$css-vars: true !default;
$prefix: "oruga-" !default;

// Animations
$speed: 300ms !default;
$speed-slow: 150ms !default;
$speed-slower: 250ms !default;
$easing: 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-rounded-border-radius: 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.375em - #{$control-border-width});
$control-padding-horizontal: calc(0.625em - #{$control-border-width});

// 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
$speed-slow: 150ms !default;
$speed-slower: 250ms !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