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:
- Oruga Theme (default Oruga style - without any dependecy)
- Bulma Theme (based on Bulma CSS framework)
- Bootstrap Theme (based on Bootstrap styling)
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:
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:
:root {
--oruga-variant-primary: green;
--oruga-variant-danger: red;
}
or a specific component variable, such as button icon width
:root {
--oruga-button-icon-width: 2.5em;
}
Oruga Theme
The Oruga Theme provides a ready-to-use and completely dependency-free styling.
npm install @oruga-ui/theme-oruga
yarn add @oruga-ui/theme-oruga
<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).
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
.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.
npm install @oruga-ui/theme-bulma
yarn add @oruga-ui/theme-bulma
<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:
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.
npm install @oruga-ui/theme-bootstrap
yarn add @oruga-ui/theme-bootstrap
<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:
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
// 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
// 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
// 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