@meridui/react

v0.2.1

Published

a month ago

React component library in plain CSS with cascade layers, so your own CSS wins. 60+ accessible components, design tokens, dark mode, RTL and server components.

Merid is an open source React component library. Its 60+ components are styled by one plain CSS file, and every rule in that file sits in a cascade layer, so the CSS you write overrides Merid without !important or specificity tricks. There is no runtime styling, no build plugin and no theme provider. The docs at meridui.dev are complete in English and Turkish.

Install

npm i @meridui/react

In a Next.js, Vite or React Router project you can let the CLI do the setup instead:

npx meridui init

It installs the package, imports the stylesheet and removes the global styles your project template ships that would override Merid, such as the Vite starter's :root font or Next.js's Arial body. Every change is shown as a diff before it is written. Merid needs React 18.2 or 19.

Usage

Import the stylesheet once, at the app entry, and use the components:

import "@meridui/react/styles.css";
import { Button, Card, Field, Heading, Input, Stack, Switch } from "@meridui/react";

export function Profile() {
  return (
    <Card>
      <Stack gap={4}>
        <Heading level={2} size="h3">Profile</Heading>
        <Field label="Display name" description="Shown on your public page.">
          <Input defaultValue="Ada Lovelace" />
        </Field>
        <Switch defaultChecked>Email me about new comments</Switch>
        <Button variant="primary">Save</Button>
      </Stack>
    </Card>
  );
}

Field wires the label, description and error to the control it wraps, including aria-describedby and aria-invalid. Compound components use dot parts (Dialog.Root, Tabs.Panel, Select.Item). Only toasts need a provider, ToastProvider.

Renders from the visual regression suite. More in the gallery, in light and dark.

Components

Each one has a page with live examples, the props table, keyboard behaviour and accessibility notes: meridui.dev/docs/components. The package ships ES modules and CommonJS with types, and its only runtime dependency is Floating UI, which positions menus, popovers and selects.

Styling and theming

Merid's stylesheet has three layers: merid.tokens, merid.base and merid.components. CSS outside them always wins, so restyling a component is ordinary CSS. Every value is a --mrd-* custom property with a light and a dark value; override one and it changes everywhere:

:root {
  --mrd-radius-md: 8px;
  --mrd-radius-card: 12px;
}

Dark mode follows the system by default. Theme, accent colour, density and text direction are attributes, so they work on the whole page or on one panel, and overlays opened from that panel keep its theme:

<div data-theme="dark" data-accent="violet" data-density="compact" dir="rtl">
  {/* everything in here follows, including portalled overlays */}
</div>

Type is set in Geist and Geist Mono, which are bundled in the package. Point --mrd-font-sans at your own font and the bundled files are never downloaded. The tokens are also published as JSON and typed JS in @meridui/tokens. With Tailwind v4, declare @layer theme, base, merid, components, utilities; so Preflight stays below Merid; the Tailwind guide has the details.

Server components

Interactive components carry their own "use client" directive and static ones render on the server, so a React Server Component can import from @meridui/react directly. In server component files, use the flat part names (DialogRoot, DialogContent, TabsList) and asChild for router links:

import Link from "next/link";
import { Button } from "@meridui/react";

<Button asChild variant="primary">
  <Link href="/projects/new">New project</Link>
</Button>

No transpilePackages entry is needed in Next.js. See Server components.

Accessibility

Interactive components follow the WAI-ARIA keyboard patterns, focus is always visible, and overlays trap and return focus. An axe suite runs in CI on every pull request, in light and dark themes and in English and Turkish. Layouts use logical properties, so right-to-left works without extra CSS, reduced motion is respected, and in Windows contrast themes controls switch to system colours. Text that only screen readers hear, such as close labels and live announcements, comes from props with English defaults, so you can translate it. Details per component are on each docs page and in the accessibility overview.

AI coding tools

npx meridui init can also add an AGENTS.md section, a Cursor rule and the config for @meridui/mcp, a read-only MCP server that gives Claude Code, Cursor or VS Code the real props and tokens. The docs publish llms.txt. More in Using Merid with AI.

Browser support

Chrome and Edge 111+, Firefox 113+, Safari 16.4+. React 18.2 and 19.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme