設定

每個 Zephora 元件的全域設定 — 用 ZephoraConfigProvider 將你的應用程式包裹一次，即可設定語言、覆蓋層 z-index 層級、portal 容器與 headless 預設值。

設定

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

屬性	型別	預設值	說明
`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.

讀取設定

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 層級

元件從具有內建備援值的 CSS 變數取得堆疊順序，因此 provider 與純 CSS 都能重新調整它們：

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

深色模式

@zephora/theme 內建自動深色模式輔助工具。useColorScheme hook 會解析出一個配色（搭配 mode: "system" 時會即時跟隨作業系統偏好），並預設將解析後的主題套用至全域：

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

屬性	型別	預設值	說明
`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.

較低階的基礎元件（primitive）也一併匯出：

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

對於伺服器渲染，colorSchemeCss(light?, dark?) 會產生一份靜態樣式表，依作業系統偏好切換主題 — 不會閃現錯誤的主題，繪製前也不需要 JavaScript。在 <html> 上設定 data-zephora-scheme 可覆寫媒體查詢（將它接到使用者的切換開關）：

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

多 slot 元件（Dialog、Sheet、Tabs、Card、Popover、Tooltip…）提供每個 slot 的類別契約：根元件接受型別為 Partial<Record<<Name>Slot, string>> 的 classNames（像 DialogSlot 這類 slot 名稱的 union 會被匯出）。slot 類別會附加在模組類別之後，且不受 unstyled 限制 — 在樣式化與非樣式化模式下都有效；在非樣式化模式中它們是唯一的類別。classNames.root 會與既有的 className prop 一併合併，className 仍會鎖定根元件並在最後套用。對於複合元件，classNames 只在根元件設定一次，並透過 context 傳遞至各部分。

伺服器元件

已發行的 @zephora/react bundle 帶有 "use client" 指示詞，因此你可以在 React Server Component 樹（Next.js app router）中直接匯入元件，而不需自行加上該指示詞 — 每個 Zephora 元件都是用戶端元件。