Getting Started

Welcome to Oeri UI — where control stays in your hands.

Oeri UI is a modular React component system built with a simple but powerful idea:

You deserve full control over your UI without fighting against the library itself.

Whether you're building prototypes, SaaS platforms, or enterprise applications, Oeri UI gives you flexible, scalable, production-ready components, hooks, and utilities — all written in clean TypeScript and styled with TailwindCSS.

No lock-ins. No hidden traps. Just your code, your rules, your creativity.

Oeri UI combines:

• ⚡ Production-ready components with built-in animation and accessibility
• 🧩 Flexible hooks and utilities to enhance React app logic
• 🎨 Design system integration powered by Tailwind utility-first styling
• 🛠️ Developer-first tooling: strong TypeScript support, configuration simplicity, and modular architecture

Use Oeri UI to speed up your development, stay consistent, and scale your projects with confidence — from prototypes to enterprise-grade apps.

Philosophy

Control every lock-in. Keep the power, not the package. Oeri UI lets you own your components — not just use them.

At the heart of Oeri UI is a simple but radical philosophy: Most UI libraries prioritize their internal structure over your freedom. They bundle opinions, add magic behaviors, and leave you wrestling with hidden constraints whenever you need something beyond the default.

Oeri UI reverses this relationship.

• Full Ownership:
  You have total control over behavior, styles, and structure. Oeri UI provides the foundation — the rest is yours to shape.

• Minimal Lock-in:
  Every component, hook, and utility is designed to be self-contained and easily replaceable.

• Adaptability First:
  Whether it's nested dialogs, mobile-specific behaviors, or animation fine-tuning, Oeri UI gives you the primitives to adapt, not dictate.

• Real-World Driven:
  Built from experience facing real-world frustrations — unnecessary complexity, bloated dependencies, waiting on library updates — Oeri UI solves the problems developers actually encounter.

• Efficient, Not Excessive:
  Install only what you need. Use only what you want. Avoid runtime bloat from unused code.

In short:
Oeri UI is here so you can stop bending your project around someone else’s idea of “good enough” — and start building exactly what you envision.

Manifesto

We believe that developer experience is productivity. Oeri UI was born out of real-world needs: building interfaces that are flexible, lightweight, and fully in your control.

Here are the principles we stand by:

• 🔧 Control Every Lock-In No feature is a black box. Every part of Oeri UI can be extended, replaced, or restructured to fit your project’s architecture — without compromise.

• 🧱 Headless by Philosophy, Opinionated by Choice We embrace headless logic. But when it saves time, we offer sensible defaults — so you can move fast and still fine-tune easily.

• 📦 Import Only What You Need Oeri UI is built to be modular. No bulky bundles, no hidden dependencies. When you import a single component, that’s all you get — clean and efficient.

• ⚡ Real-World First Every utility, hook, and component solves problems we’ve faced in production: nested dialogs, mobile query support, responsive sheets, reusable patterns — all baked in.

• 🚀 Developer-First, Always Built with TypeScript from day one. Integrated with Tailwind, Vite, Next.js, and the modern stack. Everything is designed to help you build faster, smarter, and with confidence.

Oeri UI is about freedom — the freedom to build on your own terms. You’re the architect of your app. We’re just here to give you the best tools.

Quick Installation

Get up and running in just a few steps:

1. Create a New React Project

You can use npx CLI to install the React library framework. The npx ships with npm.

This lets you install packages and run commands in one step. You can use the following command to start creating a new project.

Already have a project? You can skip this step.

Note: npx requires npm version 5.2 or later. If you’ve installed the latest versions of Node and npm, you should also have npx. Otherwise, you should upgrade Node and/or npm.

2. Install essential utilities

Add some tailwindcss class utilities like tailwind-merge and tailwindcss-animate.

Note: Oeri UI relies on TailwindCSS utilities. Make sure Tailwind is properly configured in your project.

References:

• xuxi
• TailwindCSS
• Tailwind Merge
• Tailwind CSS Animate

Once the installation completes, run your project to start editing and using the oeri module utilities.

3. Use Oeri UI Components

You can copy components directly from the docs, or import them from your own internal module (especially in monorepo or bundled setups).

import { Button } from "@/ui/button";

Everything is tree-shakable and modular — only the components you use will be included in the final bundle.

Framework Compatibility

Oeri UI works perfectly with:

This project is based on the React.js library. A React-based framework that provides features for web application development, including server-side rendering (SSR), statistical rendering (SSG), and automatic routing. It is more than just a bundling tool, as it provides the structure and conventions for building complete web applications.

A modern bundling tool that supports various frameworks including React, Svelte, and others. It uses ES Modules to provide a very fast development server and relies on Rollup for production bundling.

Fully compatible with server-side rendering (SSR), static generation (SSG), and client-side only setups.

TypeScript First

Oeri UI is developed with TypeScript at its core. Type safety, better IntelliSense, and powerful autocompletion are all included — giving you a smoother, faster development experience.

Why Oeri UI?

Oeri UI isn’t just a UI kit. It’s a mindset — designed for developers who want to build fast, flexible, and fully controlled interfaces.

Here’s why developers choose Oeri UI:

• 🧩 Modular, Not Monolithic Use only what you need. Each component, hook, and utility is standalone — no bloated bundles, no forced dependencies.

• 🛠️ Fully Customizable Components Every component is designed to be reshaped, restyled, and rebuilt to suit your project’s unique architecture — even for deeply nested or mobile-first use cases.

• 🌐 Real Use-Case Coverage Features like nested dialogs, dynamic sheet behavior, indeterminate checkboxes, scroll state tracking, and rating fractions — all based on practical needs, not just demo aesthetics.

• ⚙️ Developer-Centric Hooks Hooks like useOpenState, useWindowScroll, and useReload abstract common logic into simple, reusable building blocks.

• 🎛 Interactive Configuration, Instantly Our docs come with real-time configurators. Adjust props, preview results, and copy the code instantly — no guesswork.

• ⚡ TypeScript First, Tailwind Native Built from the ground up with strong typing and utility-first styling. You get precise IntelliSense, autocompletion, and fast iteration.

• 🧘 No Lock-In, No Waiting You don’t have to wait for pull requests or adapt to someone else’s constraints. You’re in charge — of the code, the behavior, and the roadmap.

Comparison

There are many excellent UI libraries out there — and each has its strengths. Oeri UI is built for developers who want fine-grained control, zero lock-in, and practical flexibility at every level.

🧠 Note:
Oeri UI and shadcn/ui can even complement each other — both are headless-first and Tailwind-native. But if you need more out-of-the-box control, or you're building for edge cases and deeply custom interfaces, Oeri UI may fit better.

Principles & Best Practices

Oeri UI is built not only to help you move faster — but also to help you move better. Here are the core principles and practices we encourage when using Oeri UI across your projects:

1. Clarity Over Complexity

Every component and hook is designed to be readable, predictable, and understandable. Favor simplicity and transparency over cleverness or over-abstraction.

✅ Tip: Prefer declarative patterns. Use configuration props to express intent.

2. Maximum Control, Minimal Lock-in

Oeri UI offers complete flexibility. You're encouraged to adjust, extend, or replace components freely — without fighting the framework.

🛠️ Components are headless-first and fully typed, with props exposed for total customization.

3. Design with Composition

Think in composable layers. Use primitives like Dialog, Sheet, or Dropdown to build your own UI logic — then reuse them across your app.

🧩 Grouped components (Avatar.Group, Checker.Group, etc.) let you express UI relationships clearly.

4. Accessibility Matters

Oeri UI builds on top of a11y-compliant foundations. When extending components, make sure to maintain focus management, keyboard support, and semantic markup.

♿ Always test with keyboard navigation and screen readers when relevant.

5. Lean by Default

Only import what you need. Oeri UI is not a bundle — it’s a toolbox. Use one utility or component without dragging the rest.

🚀 This helps keep your pages lightweight and performance-friendly.

6. TypeScript is Your Friend

Leverage the full power of TypeScript: autocompletion, prop inference, and error checking are all first-class citizens in Oeri UI.

🧠 Prefer strong types for better maintainability and onboarding.

7. Embrace the Tailwind Mentality

Oeri UI does not fight Tailwind — it flows with it. Write styles declaratively, override easily, and theme using your design tokens.

🎨 Use tailwind-merge and utility classes to layer your design system precisely.

By following these principles, you’ll not only write better UIs — you'll also build more consistent, maintainable, and joyful experiences for your users and your team.

Start Building

Head over to the components, hooks, or utilities section to begin building your interface, your way.

✨ You’re in full control — that’s the Oeri way.

💡 Tip:
Use the interactive configurators provided in the docs to customize each component instantly!

What’s Next

You’re ready to start building.

Here’s where to go from here:

• 🔧 Explore Components Dive into pre-built, flexible UI components — each with live demos and interactive configurators. → View Components

• ⚙️ Use Custom Hooks Take control of app logic with reusable, thoughtful abstractions like useOpenState, useReload, and more. → View Hooks

• 🛠 Leverage Utilities Streamline your workflow with utilities like cn(), match(), and isBrowser(). → View Utilities

• 🎯 Configure & Extend Fine-tune behavior, animations, responsiveness, and component states. → View Configuration

Oeri UI was built to stay out of your way and let you build your way. The docs are designed to be practical, minimal, and actionable — just like the library.

Prefer exploring visually? Most components have demo variants and real-world usage examples to guide you.

Do & Don't

Some simple practices to get the most out of Oeri UI — and avoid common mistakes.

• Use Tailwind as your design engine Oeri UI is designed to play well with utility-first CSS. Extend freely with Tailwind classes.

• Leverage interactive configurators Most components come with built-in configurators in the docs. Use them to explore variants quickly.

• Keep components lean and composable Reuse Group, Item, and Root structures to build scalable UI blocks.

• Use provided hooks for consistent state behavior Hooks like useOpenState or useReload solve real-world needs across many components.

• Customize deeply when needed You have full control. Don’t hesitate to override behavior, UI, or structure when it fits your use case.

• Use TypeScript for a smoother dev experience Every piece is strongly typed. Embrace type safety and take advantage of IDE autocompletion.

• Don’t treat Oeri UI as a theme-only system It’s not just about looks. Most components encapsulate logic, accessibility, and interactivity.

• Avoid bloated imports Only import what you use. The system is modular — take just what you need, and leave the rest.

• Don’t ignore variants, slots, or props flexibility These are key tools for adjusting behavior without rewriting or duplicating code.

• Don’t force it into non-React contexts Oeri UI is React-specific — it’s not meant for other frameworks (yet).

• Don’t forget accessibility Oeri UI aims for accessible defaults. Don’t strip out roles, labels, or keyboard handlers unless you know what you're doing.

Think of Oeri UI as a design system framework, not just a component library — it grows with your project.

✨

Build better, faster, and smarter.