WSO2 Oxygen-UI is the official design system and React component library for WSO2 products, built on top of Material-UI v7. It provides a consistent, modern, and accessible user experience across all WSO2 applications, enabling rapid development and seamless integration with the latest frontend technologies.

Oxygen-UI delivers:

• A comprehensive set of ready-to-use UI components + icons, themed for WSO2 brand and product needs
• Full compatibility with Material-UI v7.3.5 and its ecosystem
• Full compatibility with Lucide v0.553
• Support for custom WSO2 components, icons and design patterns
• Easy integration with Vite, Nx, and modern React workflows

Before you begin, ensure you have the following installed:

• Node.js (v24 or newer recommended)
• pnpm (v10 or newer recommended)

Install the main Oxygen UI library:

pnpm add @wso2/oxygen-ui @wso2/oxygen-ui-icons-react

This will automatically install all required dependencies including Material-UI, Emotion, and other peer dependencies.

Charts:

pnpm add @wso2/oxygen-ui @wso2/oxygen-ui-charts-react

Note: If using npm or yarn, you may need to install peer dependencies manually. With pnpm, peer dependencies are installed automatically.

Import any Material-UI or Oxygen-UI custom component:

import { OxygenUIThemeProvider, Button, TextField } from '@wso2/oxygen-ui';

function App() {
  return (
    <OxygenUIThemeProvider>
      <Button variant="contained">Hello World</Button>
      <TextField label="Name" />
    </OxygenUIThemeProvider>
  );
}

Note: import { Button } from '@wso2/oxygen-ui' is equivalent to import { Button } from '@mui/material'

Refer to Material-UI documentation for component usage details.

For DataGrid and DatePickers, use namespace imports:

import { DataGrid } from '@wso2/oxygen-ui';

function MyDataGrid() {
  return (
    <DataGrid.DataGrid
      rows={rows}
      columns={columns}
    />
  );
}

See the @wso2/oxygen-ui README for detailed usage.

Import Lucide icons or Oxygen-UI custom icons:

import { Bell, WSO2 } from '@wso2/oxygen-ui-icons-react';

Note: import { Bell } from '@wso2/oxygen-ui-icons-react' is equivalent to import { Bell } from 'lucide-react'

Refer to Lucide documentation for the complete icon list.

Install required dependencies:

pnpm i

To build the project and all packages:

pnpm build

To see view the usage instructions:

pnpm storybook

To run the sample app:

cd samples/oxygen-ui-test-app
pnpm dev

The workspace is organized as follows:

oxygen-ui/
├── packages/
│   ├── oxygen-ui/                        # Main Oxygen-UI component library (@wso2/oxygen-ui)
│   ├── oxygen-ui-charts-react/           # Oxygen-UI charts library (@wso2/oxygen-ui-charts-react)
│   ├── oxygen-ui-docs/                   # Oxygen-UI docs - storybook
│   ├── oxygen-ui-icons-react/            # Oxygen-UI icons library (@wso2/oxygen-ui-icons-react) 
│   └── eslint-plugin-oxygen-ui/          # ESLint plugin for enforcing Oxygen-UI import patterns
├── samples/
│   └── oxygen-ui-test-app/               # Example Vite + React app using Oxygen-UI
├── README.md
├── package.json
├── pnpm-workspace.yaml
└── nx.json

Licenses this source under the Apache License, Version 2.0 (LICENSE), You may not use this file except in compliance with the License.

(c) Copyright 2025 WSO2 LLC.