Konfiguration

Globale Einstellungen für jede Zephora-Komponente — umschließen Sie Ihre App einmal mit ZephoraConfigProvider und konfigurieren Sie Locale, Overlay-z-index-Ebenen, den Portal-Container und den Headless-Standard.

Einrichtung

import { ZephoraConfigProvider } from "@zephora/react";

export default function App() {
  return (
    <ZephoraConfigProvider
      locale="tr"
      zIndex={{ modal: 2000, toast: 2100 }}
      appendTo={typeof document !== "undefined" ? document.body : null}
      unstyled={false}
    >
      <YourApp />
    </ZephoraConfigProvider>
  );
}

ZephoraConfigProvider props

Prop	Typ	Standard	Beschreibung
`locale`	`string`	`"en"`	Active locale for component UI strings. Only "en" is embedded; load others from @zephora/theme/locales/* (module or JSON) and register with addLocale().
`zIndex`	`{ dropdown?, overlay?, modal?, popover?, toast?, tooltip?: number }`	—	Overrides the layering of floating elements. Written as --z-index-* CSS variables on the root element.
`appendTo`	`HTMLElement \| null`	`document.body`	Container that Portal-based overlays (Dialog, Select menus, Tooltip…) render into.
`unstyled`	`boolean`	`false`	Makes every component headless by default for Tailwind-first apps. A per-component unstyled prop still wins.

Die Konfiguration auslesen

import { useZephoraConfig, useLocale } from "@zephora/react";

function MyField() {
  const config = useZephoraConfig(); // { locale, zIndex, appendTo, unstyled }
  const { t, messages, locale } = useLocale();
  return <button aria-label={t("close")} />;
}

z-index-Ebenen

Komponenten beziehen ihre Stapelreihenfolge aus CSS-Variablen mit integrierten Fallbacks, sodass sowohl der Provider als auch reines CSS sie neu justieren können:

:root {
  --z-index-dropdown: 1000;
  --z-index-overlay: 1040;
  --z-index-modal: 1050;
  --z-index-popover: 1060;
  --z-index-toast: 1070;
  --z-index-tooltip: 1080;
}

Dunkler Modus

@zephora/theme liefert automatische Dark-Mode-Helfer mit. Der useColorScheme Hook ermittelt ein Schema (mit mode: "system" folgt es live der OS-Einstellung) und wendet das ermittelte Theme standardmäßig global an:

import { useColorScheme } from "@zephora/theme";

function App() {
  // mode: "light" | "dark" | "system" (default "system")
  const { scheme, theme } = useColorScheme({ mode: "system" });
  return <span>Active scheme: {scheme}</span>;
}

useColorScheme(options) props

Prop	Typ	Standard	Beschreibung
`mode`	`"light" \| "dark" \| "system"`	`"system"`	"system" follows the OS preference live; "light"/"dark" force a scheme.
`light / dark`	`Theme`	`lightTheme / darkTheme`	Theme objects used for each scheme.
`apply`	`boolean`	`true`	Write the resolved theme to document.documentElement via applyTheme.
`→ returns`	`{ scheme: "light" \| "dark"; theme: Theme }`	—	The resolved scheme and the theme object in effect.

Die tieferliegenden Primitive werden ebenfalls exportiert:

import { getSystemColorScheme, watchSystemColorScheme } from "@zephora/theme";

// Reads the OS color scheme (SSR-safe; defaults to "light").
const scheme = getSystemColorScheme(); // "light" | "dark"

// Subscribes to OS changes. Returns an unsubscribe function.
const stop = watchSystemColorScheme((next) => console.log(next));
stop();

FOUC-freies SSR

Für das Server-Rendering erstellt colorSchemeCss(light?, dark?) ein statisches Stylesheet, das Themes anhand der OS-Einstellung wechselt — kein Aufblitzen des falschen Themes, kein JavaScript vor dem Paint nötig. Das Setzen von data-zephora-scheme auf <html> überschreibt die Media Query (koppeln Sie es an einen Nutzer-Umschalter):

import { colorSchemeCss } from "@zephora/theme";

// Next.js app router — app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <style dangerouslySetInnerHTML={{ __html: colorSchemeCss() }} />
      </head>
      <body>{children}</body>
    </html>
  );
}

Slot-classNames

Mehrslot-Komponenten (Dialog, Sheet, Tabs, Card, Popover, Tooltip…) bieten einen Klassenvertrag pro Slot: Der Root akzeptiert classNames mit dem Typ Partial<Record<<Name>Slot, string>> (Slot-Namen-Unions wie DialogSlot werden exportiert). Slot-Klassen werden nach den Modulklassen angehängt und sind nicht an unstyled gebunden — sie funktionieren im gestylten wie im ungestylten Modus; im ungestylten Modus sind sie die einzigen Klassen. classNames.root wird zusammen mit dem vorhandenen className Prop zusammengeführt, das weiterhin den Root anspricht und zuletzt angewendet wird. Bei zusammengesetzten Komponenten wird classNames einmal auf dem Root gesetzt und per Context an die Teile weitergereicht.

Server-Komponenten

Das veröffentlichte @zephora/react Bundle wird mit einer "use client" Direktive ausgeliefert, sodass Sie Komponenten direkt in React-Server-Component-Bäumen (Next.js App Router) importieren können, ohne die Direktive selbst hinzuzufügen — jede Zephora-Komponente ist eine Client-Komponente.