Reference

TypeScript types

All public types are exported from the package root:

import type {
  // Color stop
  ColorStop,

  // Linear gradient
  GradientOptions,
  ColorInterpolation,

  // Radial gradient
  RadialGradientOptions,
  RadialGradientLayer,
  RadialHarmonyType,

  // Conic gradient
  ConicGradientOptions,

  // Harmony generators
  HarmonyGradientOptions,

  // Accessibility
  AccessibleGradientOptions,
  GradientWcagReport,
  WcagLevel,

  // Canvas export
  CanvasGradientConfig,
  CanvasGradientStop,
} from 'css-magic-gradient'

WcagLevel values:

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

ColorInterpolation values:

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

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
│
├── 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)
│     VueGradientPlugin        — registers $use* on the Vue instance
│     useLinearGradient / useRadialGradient / useConicGradient
│     use*Gradient hooks       — ComputedRef<string>; SSR-safe; no DOM access
│
└── React integration (src/react-gradient-plugin.ts)
      useLinearGradient / useRadialGradient / useConicGradient
      use*Gradient hooks       — string via useMemo; SSR-safe; no Vue dependency

Bundle size & peer dependencies

Entry point	Peer deps	Notes
css-magic-gradient	vue ^3.0.0 (optional)	Core functions, presets, accessibility, CSS variable utils, canvas export, Vue hooks
css-magic-gradient/vue	vue ^3.0.0	Vue hooks only (subpath alias for the main entry)
css-magic-gradient/react	react ^17.0.0 (optional)	React hooks only — no Vue dependency

The package ships as ESM + CommonJS (dist/*.js). Vue and React are optional peer dependencies — the main bundle is fully usable without either. The only runtime dependency is color-value-tools (color math for harmony generators and palette functions).

// Core
import {
  createLinearGradient,
  createTetradicGradient,
  sunsetGradient,
  createAccessibleGradient,
  extractGradientVariables,
  gradientToDataURL,
} from 'css-magic-gradient'

// Vue hooks (subpath alias)
import { useTetradicGradient } from 'css-magic-gradient/vue'

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

License

MIT