Theme ➜
Introduction
Oruga is a lightweight UI component library for Vue.js without any dependency and doesn't depend on any specific style or CSS framework (such as Bootstrap, Bulma, Tailwind, etc). Therefore, it doesn't provide a grid system or CSS utilities; however, you can easily integrate any CSS framework you like (see the demo).
Oruga provides you with a set of functional and easily customisable components, where you can define classes globally and override them locally when necessary. 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 information about customising components, go to configuration.
🦋 For a list of all available custom styles, go to themes.
🕹 To see Oruga in action, go to examples.
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.
Setup
Install Oruga with your favorite package manager:
bash
npm install @oruga-ui/oruga-nextbash
yarn add @oruga-ui/oruga-nexthtml
<script src="https://unpkg.com/@oruga-ui/oruga-next/dist/oruga.js"></script>Oruga Plugin
In order to use Oruga components, you have to register an Oruga instance to your Vue app. This instance manages the global components and configurations, as well as the current Vue app connection.
A new instance can be created by the createOruga composable. However, for a convenient usage, the package also comes with a main Oruga instance as the default package export. The instance then has to be passed to the app.use() function of your current Vue app.
To extend the default global configuration, either pass a custom configuration object when creating a new Oruga instance, or as the second argument when installing the instance to the Vue app.
See configuration for further details and available configuration options.
js
import { createApp } from "vue";
import { createOruga } from "@oruga-ui/oruga-next";
import App from "./App.vue";
const oruga = createOruga();
const app = createApp(App);
app.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 the 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.
Note: Before v0.13 the main Oruga Vue plugin had registered all components globally by default.
js
import { createOruga, Autocomplete, Sidebar } from "@oruga-ui/oruga-next";
const oruga = createOruga();
// register any necessary components globally
oruga.use(Autocomplete);
oruga.use(Sidebar);Once installed, you can use all your global registered components in an SFC like this:
html
<template>
<o-button>oruga-ui</o-button>
</template>However, if you just want to import a single component separately, without any additional programmatic functionality, you can import the individual components as needed:
vue
<script setup>
import { OButton } from "@oruga-ui/oruga-next";
</script>
<template>
<o-button>oruga-ui</o-button>
</template>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 configuration and themes.
The default Oruga theme can be added like this:
bash
npm install @oruga-ui/theme-orugabash
yarn add @oruga-ui/theme-orugahtml
<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";VSC support
If you are using Visual Studio Code (VSC), you can specify global component types by configuring compilerOptions.types in your 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.
Accessibility
Our goal is to provide components that are as accessible as possible and implement accessibility standards by default. The ARIA Authoring Practices Guide (APG) provides a set of accessibility patterns, which describes how to apply accessibility semantics to common design patterns and widget. Where possible, our components implement or support these W3C ARIA APG patterns. The patterns supported by each component can be seen at the top of its documentation page.
If you notice any accessibility issues regarding Oruga components, we encourage you to raise awareness and open an issue!
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!