Skip to content

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.

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.