Reference

TypeScript types

All public types are exported from the package root:

import type {
  // Color stop
  ColorStop,

  // Linear gradient
  GradientOptions,
  GradientDirection,
  ColorInterpolation,
  ScaleInterpolation,

  // Radial gradient
  RadialGradientOptions,
  RadialGradientLayer,
  RadialHarmonyType,

  // Conic gradient
  ConicGradientOptions,

  // Harmony generators
  HarmonyGradientOptions,

  // Accessibility
  AccessibleGradientOptions,
  GradientWcagReport,
  WcagLevel,

  // Canvas export
  CanvasGradientParams,
  CanvasLinearGradientParams,
  CanvasRadialGradientParams,
  CanvasConicGradientParams,
} from 'css-magic-gradient'

WcagLevel values:

type WcagLevel = 'AAA' | 'AA' | 'AA-large' | 'fail'

ColorInterpolation values (CSS Color Level 4 — passed to the browser as in <space> on the generated gradient string):

type ColorInterpolation = 'srgb' | 'oklch' | 'lab' | 'hsl' | 'oklab' | 'lch'

ScaleInterpolation values (JS-side color mixing for harmony/palette generators — see the note on interpolationSpace vs interpolation):

type ScaleInterpolation = 'rgb' | 'hsl' | 'oklab' | 'oklch'

CanvasGradientParams is a discriminated union over type:

type CanvasGradientParams =
  | CanvasLinearGradientParams // { type: 'linear', stops, x0?, y0?, x1?, y1? }
  | CanvasRadialGradientParams // { type: 'radial', stops, x0?, y0?, r0?, x1?, y1?, r1? }
  | CanvasConicGradientParams // { type: 'conic', stops, startAngle?, x?, y? }

// Each stop: { color: string; offset: number } — no separately exported name for it

Custom serializer / color stop example:

import type { ColorStop, GradientOptions } from 'css-magic-gradient'

const stops: ColorStop[] = [
  { color: '#ff6b6b', position: '0%' },
  { color: '#feca57', opacity: 0.8, position: '100%' },
]

const opts: GradientOptions = {
  direction: 'to right',
  interpolation: 'oklch',
}

Architecture

css-magic-gradient
│
├── createLinearGradient      — linear-gradient / repeating-linear-gradient
│     Auto-brightness mode    — lighter start stop derived from base color
│     ColorStop[] mode        — explicit stop array; per-stop opacity → rgba()
│     CSS Color Level 4       — appends `in <space>` to the gradient declaration
│
├── createRadialGradient      — radial-gradient / repeating-radial-gradient
│     Auto / explicit / layers / harmony modes
│     createRadialGradientLayers — generates multi-ring layer arrays
│
├── createConicGradient       — conic-gradient / repeating-conic-gradient
│     createRainbowConicGradient — full HSL hue cycle
│
├── Color harmony generators
│     createComplementaryGradient / createTriadicGradient
│     createAnalogousGradient / createTetradicGradient
│     createSplitComplementaryGradient / createMonochromaticGradient
│     createHueWheelGradient
│     — all use interpolateColors / createColorScale from color-value-tools
│
├── Palette generators
│     createTintGradient / createShadeGradient / createToneGradient
│     — use Oklab-based tints / shades / tones from color-value-tools
│
├── Presets (src/presets.ts)
│     15 fixed gradient strings
│
├── Accessibility (src/accessibility.ts)
│     bestGradientTextColor    — pick #000 or #fff for best contrast
│     gradientContrastRatio    — minimum contrast across 11 sample points
│     gradientWcagLevel        — detailed GradientWcagReport
│     createAccessibleGradient — iterate adjustments until target level is met
│     bestTextColor / wcagLevel / contrastRatio / isDark
│       — re-exported directly from color-value-tools (single-color equivalents)
│
├── CSS variable utilities (src/css-variables.ts)
│     extractGradientVariables — parse var() names from a gradient string
│     resolveGradientVariables — substitute variable values with a map
│
├── Canvas export (src/canvas-export.ts)
│     gradientToCanvasGradient — applies stops to a CanvasGradient
│     gradientToImageData      — renders to ImageData at given dimensions
│     gradientToDataURL        — renders to PNG data URL
│
├── Vue 3 integration (src/vue-gradient-plugin.ts, css-magic-gradient/vue only)
│     VueGradientPlugin        — registers $use* on the Vue instance
│     useLinearGradient / useRadialGradient / useConicGradient
│     use*Gradient hooks       — ComputedRef<string>; SSR-safe; no DOM access
│     Not re-exported from the package root — the only entry point that
│     actually imports `@vue/runtime-core`, so the core stays loadable with
│     no `vue` installed at all
│
└── React integration (src/react-gradient-plugin.ts, css-magic-gradient/react only)
      useLinearGradient / useRadialGradient / useConicGradient
      use*Gradient hooks       — string via useMemo; SSR-safe; no Vue dependency

SSR compatibility

The core (all create* functions, presets, accessibility, CSS variable utilities) does no DOM access at all — safe to call during SSR unconditionally. The Vue and React hooks (css-magic-gradient/vue, css-magic-gradient/react) compute their gradient strings synchronously with no browser API access either, so they're also SSR-safe out of the box — no <ClientOnly>/useEffect gating needed. Only the canvas export functions touch a canvas API, and only when called — they throw a descriptive error in an environment with neither document nor OffscreenCanvas nor a server-side canvas library, rather than silently failing.

Bundle size & peer dependencies

Entry point	Peer deps	Notes
`css-magic-gradient`	none	Core functions, presets, accessibility, CSS variable utils, canvas export — never loads `vue` or `react`, even transitively
`css-magic-gradient/vue`	`vue ^3.0.0`	Vue plugin + hooks — the only entry point that requires `vue`
`css-magic-gradient/react`	`react ^17.0.0`	React hooks only — no Vue dependency

The package ships as ESM + CommonJS (dist/*.js). The only runtime dependency of the core entry point is color-value-tools (color math for harmony generators, palette functions, and the re-exported single-color WCAG utilities).

// Core — no vue or react required
import {
  createLinearGradient,
  createTetradicGradient,
  sunsetGradient,
  createAccessibleGradient,
  extractGradientVariables,
  gradientToDataURL,
} from 'css-magic-gradient'

// Vue hooks
import { useTetradicGradient } from 'css-magic-gradient/vue'

// React hooks
import { useTintGradient } from 'css-magic-gradient/react'

License

MIT

Reference ​

TypeScript types ​

Architecture ​

SSR compatibility ​