CrystalProvider & Hooks

CrystalProvider

The root provider that manages Crystal's two-axis customization system: theme (color identity) and crystallization (personality preset).

import { CrystalProvider } from '@artasce/crystal-ui';

export default function Layout({ children }) {
  return (
    <CrystalProvider defaultTheme="onyx" defaultCrystallization="edge">
      {children}
    </CrystalProvider>
  );
}

CrystalProvider Props

Token	Variable	Value	Description
`children`	`ReactNode`	(required)	Application content
`theme`	`CrystalTheme`	—	Controlled theme (overrides internal state)
`defaultTheme`	`CrystalTheme`	'diamond'	Initial theme (uncontrolled mode)
`crystallization`	`CrystalCrystallization`	—	Controlled crystallization
`defaultCrystallization`	`CrystalCrystallization`	'clean'	Initial crystallization (uncontrolled mode)

Values update live with theme changes. Click any row to copy the CSS variable.

What It Renders

A wrapper <div> with data attributes that activate CSS tokens:

<div class="crystal-root" data-crystal="onyx" data-crystallization="edge">
  ...children
</div>

CrystalProvider vs data-crystal Attribute

For apps that only need a single, static theme (like the showcase app), you can skip CrystalProvider entirely and set data-crystal directly on <html>:

<html data-crystal="tanzanite">

Use CrystalProvider when you need runtime theme switching or the useCrystalTheme hook.

Hooks

useCrystalTheme

Access and update theme/crystallization from any component inside CrystalProvider.

import { useCrystalTheme } from '@artasce/crystal-ui';

function ThemeSwitcher() {
  const { theme, setTheme, crystallization, setCrystallization } = useCrystalTheme();

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="diamond">Diamond</option>
      <option value="onyx">Onyx</option>
      <option value="tanzanite">Tanzanite</option>
    </select>
  );
}

useCrystalScale

Fibonacci-based tile scale utilities.

import { useCrystalScale } from '@artasce/crystal-ui';

function Component() {
  const { getSize, getNextScale, scales } = useCrystalScale();

  console.log(getSize('card'));      // 104
  console.log(getNextScale('card')); // 'panel'
  console.log(scales);              // { dot: 4, micro: 8, icon: 16, ... }
}

Scale	Size	Use Case
`dot`	4px	Status indicators
`micro`	8px	Spacing, icons
`icon`	16px	Small icons
`icon-plus`	24px	Medium icons
`chip`	40px	Chips, tags
`mini-card`	64px	Compact cards
`card`	104px	Standard cards
`panel`	168px	Panels, sidebars
`detail`	272px	Detail views
`full`	440px	Full sections

useCrystallization

Convenience hook to get the current crystallization preset.

import { useCrystallization } from '@artasce/crystal-ui';

const crystallization = useCrystallization(); // 'clean' | 'dream' | 'edge' | 'luxe' | 'bold'

usePrefersReducedMotion

Detects and tracks the user's reduced motion OS preference. Updates reactively when the preference changes.

import { usePrefersReducedMotion } from '@artasce/crystal-ui';

function AnimatedComponent() {
  const prefersReduced = usePrefersReducedMotion();

  if (prefersReduced) {
    return <div>Static content</div>;
  }

  return <div className="animate-bounce">Animated content</div>;
}

CrystalProvider Props

On this page