Configuratie

Globale instellingen voor elke Zephora-component — wikkel uw app één keer in ZephoraConfigProvider en configureer locale, overlay-z-index-lagen, de portal-container en de headless-standaard.

Setup

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	Type	Standaard	Beschrijving
`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.

De configuratie uitlezen

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-lagen

Componenten ontlenen hun stapelvolgorde aan CSS-variabelen met ingebouwde fallbacks, zodat zowel de provider als gewone CSS ze opnieuw kan afstemmen:

: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;
}

Donkere modus

@zephora/theme levert automatische donkere-modus-helpers. De useColorScheme hook bepaalt een schema (met mode: "system" volgt het live de OS-voorkeur) en past standaard het bepaalde thema globaal toe:

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	Type	Standaard	Beschrijving
`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.

De onderliggende primitives worden ook geëxporteerd:

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-vrije SSR

Voor server-rendering bouwt colorSchemeCss(light?, dark?) een statisch stylesheet dat themes wisselt op basis van de OS-voorkeur — geen flits van het verkeerde thema, geen JavaScript nodig vóór het painten. Het instellen van data-zephora-scheme op <html> overschrijft de media query (koppel het aan een gebruikersschakelaar):

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

Componenten met meerdere slots (Dialog, Sheet, Tabs, Card, Popover, Tooltip…) bieden een klassecontract per slot: de root accepteert classNames getypeerd als Partial<Record<<Name>Slot, string>> (slot-naam-unions zoals DialogSlot worden geëxporteerd). Slot-klassen worden na de moduleklassen toegevoegd en zijn niet afhankelijk van unstyled — ze werken in zowel gestylede als ongestylede modus; in ongestylede modus zijn zij de enige klassen. classNames.root wordt samengevoegd met de bestaande className prop, die de root blijft aansturen en als laatste wordt toegepast. Bij samengestelde componenten wordt classNames één keer op de root ingesteld en via context aan de onderdelen doorgegeven.

Server-componenten

De gepubliceerde @zephora/react bundle wordt geleverd met een "use client" directive, zodat u componenten rechtstreeks binnen React Server Component-bomen (Next.js app router) kunt importeren zonder de directive zelf toe te voegen — elke Zephora-component is een client-component.