https://github.com/davec6662/borealui
A highly customizable, accessible React and Next.js component library with SCSS-powered theming.
https://github.com/davec6662/borealui
component library nextjs react-components scss typescript-react uikit
Last synced: 2 months ago
JSON representation
A highly customizable, accessible React and Next.js component library with SCSS-powered theming.
- Host: GitHub
- URL: https://github.com/davec6662/borealui
- Owner: DaveC6662
- License: mit
- Created: 2025-07-27T01:54:53.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-11T17:33:24.000Z (10 months ago)
- Last Synced: 2025-08-11T19:33:25.463Z (10 months ago)
- Topics: component, library, nextjs, react-components, scss, typescript-react, uikit
- Language: TypeScript
- Homepage: https://www.borealui.ca
- Size: 3.68 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Boreal UI
A **highly customizable**, **accessible** React and Next.js component library with SCSS-powered theming.
Offers both Core (framework-agnostic React) and Next.js-optimized variants for seamless integration in any project.
---
## Features
- **Dual Build Support:**
Use `boreal-ui/core` for any React project or `boreal-ui/next` for Next.js apps.
- **SCSS-Based Theming:**
Override color, typography, spacing, border, and shadow variables to perfectly match your brand.
- **Accessibility First:**
WCAG-friendly out of the box. Includes keyboard navigation, ARIA roles, and robust focus states.
- **Rich Component Set:**
Buttons, IconButtons, Cards, Accordions, Modals, Tabs, DataTable, Avatar, Badge, Tooltip, FileUpload, EmptyState, and more.
- **TypeScript Native:**
All components include full prop typing and interfaces for an exceptional developer experience.
---
## Installation
```bash
npm install boreal-ui
```
---
## Quick Usage
### Including Global Styles
**For Next.js :**
In your globals.css (or globals.scss), add the following at the top:
```css
@import "boreal-ui/next/globals.css";
```
Then, make sure this global file is included in your layout or \_app.tsx:
```tsx
import "./globals.css"; // or "./globals.scss"
```
**For React (Core):**
If you're using boreal-ui/core, import the base styles in your main entry (e.g., index.tsx or App.tsx):
```tsx
import "boreal-ui/core/globals.css";
```
### Importing Components
**For React (Core):**
```tsx
import { Button } from "boreal-ui/core/Button";
import { Card } from "boreal-ui/core/Card";
```
**For Next.js (Optimized):**
```tsx
import { Button } from "boreal-ui/next/Button";
import { Card } from "boreal-ui/next/Card";
```
---
## Global Configuration
Boreal UI lets you define project-wide style defaults (theme, rounding, shadow, size) in a single config API.
**Call the config API**
```ts
import { setBorealStyleConfig } from "boreal-ui/config/[next|core]";
setBorealStyleConfig({
defaultTheme: "secondary", // "primary" | "secondary" | "tertiary" | "quaternary"
defaultRounding: "medium", // "none" | "small" | "medium" | "large" | "full"
defaultShadow: "light", // "none" | "light" | "medium" | "strong" | "intense"
defaultSize: "large", // "xs" | "small" | "medium" | "large" | "xl"
});
```
Call this once early in your app before rendering any components.
These defaults apply globally, but you can override them per component as needed:
```tsx
Custom Button
```
## Theming & Custom Color Schemes
Boreal UI supports custom color schemes through the `ThemeProvider`.
**Wrap your app (typically in `_app.tsx` or a custom provider):**
```tsx
"use client";
import { ThemeProvider } from "boreal-ui";
export default function RootLayout({ children }) {
return (
{children}
);
}
```
**Theme property reference:**
| Property | Description |
| ----------------- | -------------------------------- |
| `name` | Unique identifier for the scheme |
| `primaryColor` | Main UI color |
| `secondaryColor` | Accent color |
| `tertiaryColor` | Additional accent |
| `quaternaryColor` | Additional accent |
| `backgroundColor` | Background/base color |
---
## Post-Install Verification
After installation, we recommend testing the following in your app:
- Component renders correctly and styles are applied.
- Custom theme is working when passed via ThemeProvider.
- Global config overrides (theme, size, etc.) are applied.
- No console errors or missing styles on first render.
## Why Use Boreal UI?
- Enforces consistent styling and branding across your project.
- Save time: define defaults once, override only when needed.
- Switch between multiple color schemes easily (great for light/dark mode).
- Fully accessible and ready for production.
---
## Contributing
1. Fork this repo.
2. Create a feature branch: `git checkout -b feat/my-component`
3. Commit your changes: `git commit -m "Add MyComponent"`
4. Push to your fork: `git push origin feat/my-component`
5. Open a Pull Request.
**Include**
- Component logic (TSX)
- Styles (SCSS)
- Tests (Jest/Cypress)
- Storybook stories
- Docs/comments for props
---
## License
MIT © [Davin Chiupka](https://davinchiupka.com)