oruga

Features

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

• CSS framework agnostic: No dependency on a specific CSS framework/library but you can easily integrate the components with one of them because they are fully customizable in different ways
• Components with steroids: most of the components aren't a simple wrapper of native elements but they add new and custom features
• Lightweight: no other internal dependency and import only components that you need

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

Documentation

Browse online documentation here.

💅 For more info about components customization, read carefully the "customization" section in the documentation.

🕹 To see Oruga in action, go to the "example" section in the documentation.

Note: the source code of the documentation examples can be found in the examples directories for each component, it serves as the demo as well.

Quick start

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

Setup Oruga

1. Install Oruga.

npm install @oruga-ui/oruga-next

2. Import the components:

• To get started, create a new Oruga instance by the createOruga composable. The instance then has to be passed to the app.use() function of your current Vue app.

  import { createApp } from "vue"
  import { createOruga } from "@oruga-ui/oruga-next";
  
  const oruga = createOruga();
  
  createApp(...).use(oruga, {
    // here goes the global config
  });
  

• To take advantage of bundler’s tree-shaking optimisations, no components are registered globally by default. If you want to register a component globally, extend your Oruga instance with the relevant component plugin. This makes the respective component and its subcomponents, as well as any related programmatic components, globally available.

  import { createOruga, Autocomplete, Sidebar } from "@oruga-ui/oruga-next";
  
  const oruga = createOruga();
  
  // register any necessary components globally
  oruga.use(Autocomplete);
  oruga.use(Sidebar);
  

• or import them in your SFC.

Customization

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.

Please read the "configuration" section in Oruga documentation.

If you want to see an example with a fully customized registration form using Tailwind, Bulma, Bootstrap, Material or any other CSS framework have a look at the official Oruga multiframework example (source code available here) or if you're more familiar with TailwindCSS 2 give our official TailwindCSS Demo a try (source code here)

Using Oruga with Nuxt

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

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

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

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

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

Contributing

Please see the contributing guidelines.

Contact us 👾

➜ Join the Oruga Discord server.

Versioning

Oruga uses Semantic Versioning 2.0.0 for package versions.

While it's still in beta, versions will follow this pattern: v0.Y.Z, where:

• Y: Major (breaking changes)
• Z: Minor or patch

Core Team

Contributors

Thank you to everyone involved for improving this project, day by day 💚

Complete list.

Credits

Oruga logo designed by Matteo Guadagnini

License

Code released under MIT license.