@zeromustafa/morph

Plug-and-play animated gradients for any web component. Background cover, element fill, text outline — randomized by default from 380+ curated palettes. WebGL, Canvas 2D, or pure CSS.

npm install @zeromustafa/morph

Quick Start

import { OrbBackground, OrbFill, OrbGradientText, orbGradient } from '@zeromustafa/morph'

// 1. Full-page animated background (WebGL) ← random preset every mount!
<div style={{ position:'relative', height:'100vh' }}>
  <OrbBackground />
</div>

// 2. Gradient fill inside a card (Canvas 2D)
<div className="card">
  <OrbFill type="radial" preset="emerald" />
</div>

// 3. Gradient text (CSS background-clip)
<OrbGradientText as="h1" preset="lava">Hello World</OrbGradientText>

// 4. CSS string only — no React, no WebGL
myDiv.style.background = orbGradient({ preset:'midnight', angle:180 })

Exports

React Components

| Export | Deps | What | |--------|------|------| | <OrbBackground /> | React, three, @react-three/* | Full-viewport WebGL animated background | | <OrbFill /> | React only | Canvas 2D animated gradient inside any container | | <OrbGradientText /> | React only | Text with gradient fill via CSS background-clip |

Utilities (vanilla JS — zero dependencies)

| Export | Returns | What | |--------|---------|------| | orbGradient(opts) | string | CSS gradient value (linear-gradient(...) or radial-gradient(...)) | | resolveColors(opts) | string[] | 8-color hex array resolved from preset/colors/random | | randomPreset() | string | Random preset name from 385+ palettes | | randomColors() | string[] | 8 random hex colors | | PRESETS | object | All ~385 named 8-color palettes | | DEFAULT_OPTIONS | object | Default config object | | hexToRgb(hex) | [r,g,b] | Hex-to-RGB converter |

API Reference

<OrbBackground>

Full-viewport WebGL animated gradient (Three.js / R3F). Positions absolute; inset:0; z-index:-1.

<OrbBackground preset="lava" />

| Prop | Type | Default | Description | |------|------|---------|-------------| | preset | string | null (random) | Named palette from PRESETS | | colors | string[8] | — | Override with custom hex colors | | noiseType | 0\|1\|2\|3 | 0 | simplex | perlin | worley | fbm | | frequency | number | 0.4 | Noise frequency | | amplitude | number | 0.1 | Displacement strength | | speed | number | 0.1 | Animation speed | | materialType | string | 'basic' | 'basic' | 'standard' | 'glass' | | className | string | '' | CSS class on wrapper div |

Color resolution order: colors prop → preset name → random palette.

<OrbFill>

Canvas 2D animated gradient that fills its parent container.

<div style={{ position:'relative', width:400, height:300 }}>
  <OrbFill type="mesh" preset="neon" />
  <h1 style={{ position:'relative', zIndex:1 }}>Content</h1>
</div>

| Prop | Type | Default | Description | |------|------|---------|-------------| | preset | string | null (random) | Named palette | | colors | string[8] | — | Custom hex colors | | type | string | 'linear' | 'linear' | 'radial' | 'mesh' | | angle | number | 135 | Angle in degrees (linear only) | | noiseType | 0\|1\|2\|3 | 0 | Noise algorithm | | frequency | number | 0.6 | Noise frequency | | amplitude | number | 0.2 | Displacement strength | | speed | number | 0.3 | Animation speed | | animated | boolean | true | Enable/disable animation | | className | string | — | Container class | | style | object | — | Container style |

<OrbGradientText>

Text with a gradient fill using CSS background-clip: text. Renders as <span> by default.

<OrbGradientText as="h1" preset="lava" angle={45}>
  Gradient Text
</OrbGradientText>

| Prop | Type | Default | Description | |------|------|---------|-------------| | preset | string | null (random) | Named palette | | colors | string[] | — | Custom hex colors | | type | string | 'linear' | 'linear' | 'radial' | | angle | number | 135 | Angle in degrees | | as | string | 'span' | HTML element tag | | className | string | — | CSS class | | style | object | — | Inline styles | | ...rest | — | — | Spread onto the element |

orbGradient(options)

Generate a CSS gradient string. No React, no WebGL.

import { orbGradient } from '@zeromustafa/morph'

// Linear gradient
orbGradient({ preset:'lava', angle:180 })
// → "linear-gradient(180deg, #ff4b1f 0%, #ff9068 14%, ...)"

// Radial gradient
orbGradient({ type:'radial', preset:'emerald' })
// → "radial-gradient(circle, #00b09b 0%, #96c93d 14%, ...)"

// Custom colors
orbGradient({ colors:['#fff','#000','#f00'], angle:45 })
// → "linear-gradient(45deg, #fff 0%, #000 50%, #f00 100%)"

| Option | Type | Default | Description | |--------|------|---------|-------------| | preset | string | null (random) | Named palette | | colors | string[] | — | Custom hex colors | | gradientType | string | 'linear' | 'linear' | 'radial' | | angle | number | 135 | Angle in degrees |

resolveColors(options)

Resolve an 8-color array. Resolution chain: colors prop → preset name → random.

import { resolveColors } from '@zeromustafa/morph'

resolveColors({ preset:'midnight' })
// → ["#0f0c29","#302b63","#24243e","#1a1a2e","#16213e","#0f3460","#533483","#000000"]

resolveColors()  // random preset
// → random 8-color array

Dependency Tree

@zeromustafa/morph
├── OrbBackground       → peer: react, three, @react-three/*, zustand
├── OrbFill             → peer: react
├── OrbGradientText     → peer: react
├── orbGradient()       → none (vanilla JS)
├── resolveColors()     → none (vanilla JS)
└── PRESETS / utils     → none (vanilla JS)

Tree-shaking: Modern bundlers (Vite, webpack 5, Rollup) remove unused exports. Import only orbGradient and you won't bundle Three.js.

Full Example

import { OrbBackground, OrbFill, OrbGradientText, orbGradient } from '@zeromustafa/morph'

export default function Page() {
  return (
    <main style={{ position:'relative', minHeight:'100vh' }}>
      {/* Full-page WebGL background — different random preset every mount */}
      <OrbBackground />

      {/* Hero with gradient text */}
      <OrbGradientText as="h1" preset="lava" angle={45}
        style={{ fontSize:'4rem', fontWeight:900, textAlign:'center' }}>
        Welcome
      </OrbGradientText>

      {/* Card with animated fill */}
      <div style={{ position:'relative', maxWidth:400, margin:'2rem auto', borderRadius:16, overflow:'hidden' }}>
        <OrbFill type="radial" preset="emerald" />
        <div style={{ position:'relative', zIndex:1, padding:24 }}>
          <h2>Feature Card</h2>
          <p>This card has an animated gradient fill behind it.</p>
        </div>
      </div>

      {/* Pure CSS gradient background on any element */}
      <footer style={{ background: orbGradient({ preset:'midnight', angle:0 }), padding:40 }}>
        <p style={{ color:'white' }}>CSS gradient footer — no WebGL needed.</p>
      </footer>
    </main>
  )
}

Install Locally

# 1. Build the library
cd /path/to/morph
npm run build:lib

# 2. Link globally
npm link

# 3. Use in your project
cd /path/to/your-project
npm link @zeromustafa/morph

Or with the file: protocol in your project's package.json:

{
  "dependencies": {
    "@zeromustafa/morph": "file:../morph"
  }
}

License

MIT · Built by Nous Research