Cấu hình

Cài đặt toàn cục cho mọi component Zephora — bọc ứng dụng của bạn một lần bằng ZephoraConfigProvider và cấu hình locale, các lớp z-index của overlay, container portal và mặc định headless.

Thiết lập

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	Kiểu	Mặc định	Mô tả
`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.

Đọc cấu hình

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")} />;
}

Các lớp z-index

Các component lấy thứ tự xếp chồng từ các biến CSS có sẵn giá trị dự phòng, nên cả provider lẫn CSS thuần đều có thể tinh chỉnh lại chúng:

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

Chế độ tối

@zephora/theme đi kèm các helper chế độ tối tự động. Hook useColorScheme phân giải một scheme (với mode: "system" nó theo dõi trực tiếp tùy chọn của hệ điều hành) và theo mặc định áp dụng theme đã phân giải trên toàn cục:

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	Kiểu	Mặc định	Mô tả
`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.

Các primitive cấp thấp hơn cũng được xuất ra:

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();

SSR không FOUC

Đối với render phía máy chủ, colorSchemeCss(light?, dark?) tạo một stylesheet tĩnh chuyển đổi theme theo tùy chọn của hệ điều hành — không nhấp nháy sai theme, không cần JavaScript trước khi vẽ. Đặt data-zephora-scheme trên <html> sẽ ghi đè media query (hãy nối nó với một nút chuyển của người dùng):

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

Các component nhiều slot (Dialog, Sheet, Tabs, Card, Popover, Tooltip…) cung cấp một hợp đồng class cho từng slot: phần gốc chấp nhận classNames được định kiểu là Partial<Record<<Name>Slot, string>> (các union tên slot như DialogSlot đều được xuất ra). Các class của slot được thêm vào sau các class của module và không bị chi phối bởi unstyled — chúng hoạt động ở cả chế độ có style lẫn không style; ở chế độ không style, chúng là những class duy nhất. classNames.root hợp nhất cùng với prop className hiện có, prop này vẫn nhắm vào phần gốc và được áp dụng cuối cùng. Đối với các component ghép, classNames được đặt một lần trên phần gốc và truyền tới các phần con qua context.

Server component

Bundle @zephora/react được phát hành đi kèm chỉ thị "use client", nên bạn có thể import các component trực tiếp bên trong các cây React Server Component (Next.js app router) mà không cần tự thêm chỉ thị — mọi component Zephora đều là client component.