Oruga

Introduction ​

Oruga is a lightweight UI components library for Vue.js without any dependency.
It offers a set of easily customisable components and doesn't depend on any specific style or CSS framework (like Bootstrap, Bulma, TailwindCSS, etc). Therefore, it doesn't provide a grid system or CSS utilities, but you can integrate any CSS framework you like (see the demo).
Oruga provides you with a set of functional components, so you can focus only on the UI/UX aspects of your application and can be entirely flexible for future changes without having to touch a line of JavaScript.

If you need a component library and want to easily apply your custom styles, Oruga is the library for you! 🐛

In addition, if you don't want to style everything yourself, we've created several themes to provide you with a variety of ready-to-use styles. 🦋

🐛 Oruga is available for Vue.js version 3.x.

💅 For more info about components customisation, go to #customisation.

🦋 For a list of all available themes, go to #themes.

🕹 To see Oruga in action, go to #examples.

Setup ​

bash
npm install @oruga-ui/oruga-next
bash
yarn add @oruga-ui/oruga-next
html
<script src="https://unpkg.com/@oruga-ui/oruga-next/dist/oruga.js"></script>

Oruga for Vue 2.x deprecated

Due to EOL for Vue 2.x at the end of the year 2023, from now on Oruga for Vue 2 (@oruga-ui/oruga) is deprecated. Further enhancements will only be developed for @oruga-ui/oruga-next.

Full bundle import ​

You can import all Oruga components using the main plugin export:

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

createApp(...).use(Oruga);

To specify some global configuration, a configuration object (see #customisation) can be passed as second parameter to the Oruga plugin.

After the installation, you can use all the components in an SFC like this:

html
<template>
  <o-button>oruga-ui</o-button>
</template>

Individual components imports (tree shaking) ​

Each component can also be added individually using its own plugin. This adds the component, including its subcomponents and programmatic components:

js
import { createApp } from 'vue';
import { Autocomplete, Sidebar } from '@oruga-ui/oruga-next';

createApp(...)
  .use(Autocomplete)
  .use(Sidebar);

When using individual components, no configuration is initialised by default. To add some configuration we provide an OrugaConfig plugin which can be used to add some global configuration:

js
import { OrugaConfig } from '@oruga-ui/oruga-next';

const options: OrugaOptions = { ... }

createApp(...).use(OrugaConfig, options);

However, if you just need to import a single component separately, without any additional programmatic functionalities, you can import individual components like this:

js
import { createApp } from 'vue';
import { OAutocomplete, OSidebar } from '@oruga-ui/oruga-next';

createApp(...)
  .component(OAutocomplete)
  .component(OSidebar);

Styling ​

Oruga comes without any styling by default, but you can easily add your own custom styles or an additional theme package. For more details and a list of available themes, see #customisation and #themes.

The default Oruga theme can be added like this:

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.min.css" />
scss
@import '@oruga-ui/theme-oruga/dist/scss/oruga.scss';

Volar support ​

If you are using Volar, you can specify global component types by configuring compilerOptions.types in tsconfig.json.

js
// tsconfig.json
{
  "compilerOptions": {
    // ...
    "types": ["@oruga-ui/oruga-next/volar"]
  }
}

Nuxt module ​

Oruga doesn't provide a Nuxt.js module at the moment.

But you can use Nuxt.js plugins system adding a file (e.g. oruga.js) in your plugins folder containing:

js
import Oruga from '@oruga-ui/oruga-next';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(Oruga);
});

To make this plugin available in your app, add this file to the plugins array in your nuxt.config.js:

js
plugins: [{ src: '~plugins/oruga.js' }]

To understand how the plugins work with Nuxt.js, take a look at the NuxtJS plugin documentation.

Community ​

Community involvement and contribution is one of the most important aspects of an open source project. We invite you to contribute to this project! There are many ways to help — from creating pull requests to our open source code bases, to filing issues so we can improve Oruga for everyone.

If you need generalized help or want to make connections within the community, consider joining the official Discord.

Join the Oruga Discord server →

Open issues on GitHub (bugs and features) - GitHub issues are for feature requests and bug reports. If you've found a bug, please create a GitHub issue! Feature requests are always welcome. If you have an idea for improvements, let us know!

Create a theme to share - We have created some themes for you. However, if you have created a nice theme for Oruga? Let us know! We will be happy to include links to and share high quality content in our docs.

Examples ​

TailwindCSS, Bootstrap 5, Bulma and Material demo 🧶 ​

TailwindCSS 2 Recipe Demo 🍝🍔🍟 ​

This simple demo shows a simple recipe website. Oruga components like Input, Radio, Loading, Switch, Collapse etc are customized using TailwindCSS 2!

Articles ​

Released under the MIT License.

Copyright © 2020-2024 Walter Tommasi