Getting Started
Changelog
A full changelog can be found here.
Nuxt
If you are using Nuxt, please head over to our Nuxt module documentation to get started.
Installation
Step 1: Install dependencies
Install the npm package with your corresponding package manager:
pnpm add sit-onyx@betanpm install sit-onyx@betayarn install sit-onyx@betaStep 2: Imports
After that, import the global CSS file:
import { createApp } from "vue";
import { createOnyx } from "sit-onyx";
import "sit-onyx/style.css";
// by default, no onyx styles will have side affects on your global application styles like <body> etc.
// when building a whole application with onyx, we recommend also importing the following global styles
// which will apply the correct application background color, font styles etc.:
// import "sit-onyx/global.css";
const onyx = createOnyx();
const app = createApp(App);
app.use(onyx);Step 3: Install fonts
Finally, install the recommended onyx font families by following our typography docs.
Step 4: Use components
Components are now ready to be used, e.g.:
<script lang="ts" setup>
import { OnyxButton } from "sit-onyx";
</script>
<template>
<OnyxButton label="Click me" />
</template>You can check all onyx components and their documentation in our Storybook.
First steps recommended
Here are some further steps we recommend to take a look at when setting up your new application:
Layout components
onyx provides layout components for easily setting up common layouts for the app, pages etc. which also take care of ensuring correct scroll containers etc.
Here is an example how a default application looks like when using layout components:
<script lang="ts" setup>
import { OnyxAppLayout, OnyxPageLayout, OnyxNavBar } from "sit-onyx";
</script>
<template>
<OnyxAppLayout>
<template #navBar>
<OnyxNavBar app-name="My app" />
</template>
<OnyxPageLayout>
<div class="onyx-grid-container">Your page content here...</div>
</OnyxPageLayout>
</OnyxAppLayout>
</template>Customize CSS
For most cases, all onyx components already provide properties to easily use supported features. However, there might be some custom requirements in your project where you need to override styles / CSS.
All onyx components are designed to be easily customized with custom CSS. Just look up the CSS class that you want to customize via your browser dev tools and define custom CSS as shown below.
Option 1: In a single Vue file recommended
For most cases when overriding onyx styles, we recommend to override them inside a single .vue file with scoped styles so the changes only affect components in this file and do not have global side effects on other components of your application.
Note the usage of the :deep() selector. For more information, see the Vue docs.
<style scoped>
:deep(.onyx-input__label) {
color: red;
}
</style>Option 2: Globally
Be careful when overriding styles globally since it will affect EVERY component in your application.
.onyx-input__label {
color: red;
}Browser Support
Onyx works best with the following browser versions. Older versions might also work but we can't guarantee full compatibility.
Chrome
Version ≥ 109
Edge
Version ≥ 128
Firefox
Version ≥ 115
Safari
Version ≥ 17.6
Samsung Internet
Version ≥ 25
Safari on iOS
Version ≥ 15.6-15.8
More information (.browserslistrc file)
# Browsers that we support
> 0.5%, last 2 versions, Firefox ESR,
not dead, not op_mini all, not KaiOS < 4.0