Customisation

Oruga's superpower is its configurability and its CSS framework agnostic approach.
Each component can be individually customised and configured by defining specific classes using a class-mapping approach. Therefore, Oruga comes without any styling by default. However, there are several official predefined configurations called themes, which you can include and extend to give your application a individual look and feel. And all components came with predefined classes by default.

You can customise component classes in 3 different ways:

• Global configuration
• Individual configuration
• Programmatically configuration

INFO

Although all components have predefined classes, Oruga allows you to easily override the style of existing components by appending one or more classes, either globally or programmatically, to individual components.

To configure a component, each component has a set of class properties which can be found in the Class Inspector section of a component (see for example Autocomplete class inspector). Here you can inspect the elements affected by each class property using the Class Prop Inspector.

Global Configuration

The easiest way to customise your components is set up a global configuration object with a class-mapping for each component.

The Config object is defined as:

{
    [globalProp]: string|boolean|number|function|....,
    [componentName]: {
        override: boolean,
        [classProp]: string|boolean|number|function|....
    }
}

INFO

While using TypeScript, the configuration object is defined by the type OrugaOptions.

For example:

import type { OrugaOptions } from "@oruga-ui/oruga-next";

const config: OrugaOptions = {
    iconPack: "fas",
    button: {
        override: true,
        rootClass: 'btn',
        roundedClass: 'btn-rounded',
        ...
    }
}

The configuration object can the passed as second option parameter to the Oruga plugin:

import { createApp } from 'vue';
import Oruga from '@oruga-ui/oruga-next';

createApp(...)
    .use(Oruga, {
        autocomplete: {
            rootClass: 'autocomplete-root',
            itemClass: 'autocomplete-item',
            ...
        }
        ...
    });

You can also use an array to specify more than one class or a function to extend or override classes in a component. In case you use a function, a suffix is provided by the component and it can be used inside the function. For example, positionClass of the Dropdown component provides a suffix to specify the menu position (top, bottom), in this case you may define a function and append the suffix to the base class name.

createApp(...)
    .use(Oruga, {
        dropdown: {
            rootClass: ['dropdown-root', 'additional-class'],
            positionClass: {
                class: (suffix) => `dropdown-menu-${suffix}`,
            },
            itemClass: 'dropdown-item',
        }
        ...
    });

For a better customisation experience, this function accepts the component's read-only props as a second parameter. For example, when using Bootstrap you may want to apply variants to buttons only when the element is not outlined:

createApp(...)
    .use(Oruga, {
        button: {
            rootClass: (_, props) => {
                if (props.iconRight) return 'has-icons-right';
            },
            variantClass: (variant, props) => {
                if (!props.outlined) return `btn-${variant}`;
            }
        },
        ...
    });

Component properties

You can add classes to a component directly using the specific class properties, which can be found in the Class Inspector section of a component:

<o-autocomplete 
    root-class="autocomplete-root" 
    item-class="autocomplete-item" />

Overriding classes

In case you want to override existing default Oruga classes completely, either for one component or for all, you can act as above and set the field override to true:

createApp(...)
    .use(Oruga, {
        autocomplete: {
            override: true,
            rootClass: 'autocomplete-root',
            itemClass: 'autocomplete-item',
            ...
        }
    });

INFO

While using themes such as Bootstrap or Bulma, this feature is used to remove all default classes and to create specific theme configurations.

This property can also be passed directly to the component:

<o-autocomplete
    override
    rootClass="autocomplete-root">

WARNING

In this case, the override property replaces all existing predefined classes for this component completely, ignoring your configuration.

You can also specify the override behaviour for each class individually:

createApp(...)
    .use(Oruga, {
        autocomplete: {
            rootClass: {
                override: true
                class: 'autocomplete-root',
            },
            itemClass: 'autocomplete-item',
            ...
        }
    });

Transform classes

In case you want to transform applied classes you can use the transformClasses function directly in your configuration, for each component or globally for any component:

createApp(...)
    .use(Oruga, {
        // global transform function
        transformClasses: (appliedClasses: string) => {
            return appliedClasses.replace(/-/g, '--')
        }
        button: {
            // component scoped transform function
            transformClasses: (appliedClasses: string) => {
                return appliedClasses.replace(/-/g, '--')
            }
        }
        ...
    })

Global Props

Field	Description	Default
override	In case you want to completely override all the existing Oruga default classes for each component, you can specify the override behaviour here globaly.	null
iconPack	Icon pack used internally and on the Icon component attribute	'mdi'
iconComponent	Define a specific icon component	null
statusIcon	Show status icon using field and variant prop	true
statusVariantIcon	Default status variant and icon mapping name	{   'success': 'check',   'danger': 'alert-circle',   'info':'information',   'warning': 'alert' }
teleportTarget	Define the default target element for teleport and programmatic feature	document.body
useHtml5Validation	Enable HTML5 form validation attribute	true
invalidHandler	Callback function that allows for custom behavior when HTML constraint validation would visually report that a field is invalid. Takes the input and its parent field (if any) as arguments.	null

Have a look at the docs of each component to know all the customisable fields/props by config.