Particle Morph Library

Reusable Three.js particle morph library for sphere-to-text animations with customizable colors, hover feedback, and morph timing.

Features

• Sphere and text morph targets
• Custom text via text
• Morph timing via morphDurationMs
• Editable color themes and presets
• Pointer hover color feedback
• Separate demo for local testing

What is inside

• src/core/: main library class and runtime behavior
• src/config/: default values and editable color presets
• src/generators/: shape builders like sphere and text
• src/utils/: small helpers like morph timing
• example/: a demo page that uses the library
• package.json: local package setup, separate from your main project

Installation

npm install reyhan-particle-morph-library three

Quick Start

import { ParticleMorph, colorPresets } from "reyhan-particle-morph-library";

const morph = new ParticleMorph({
  container: document.getElementById("scene"),
  particleCount: 30000,
  text: "ZINAV",
  morphDurationMs: 1400,
  colors: colorPresets.candyPlasma,
});

morph.setText("ZINAV");
morph.setSphere();
morph.destroy();

Public API

• new ParticleMorph(options)
• setText(text)
• setSphere()
• destroy()

Config Props

• container: required DOM element for the renderer
• particleCount: number of particles
• text: initial text to render instead of starting from the sphere
• morphDurationMs: morph timing in milliseconds
• textFont: canvas font used for text sampling
• sphereRadius: sphere size
• colors.baseStart: first base color
• colors.baseEnd: second base color for the mixed particle palette
• colors.hover: color used when the pointer moves over particles

Project Structure

• Change default props in src/config/defaults.js
• Add new reusable themes in src/config/colorPresets.js
• Change sphere generation in src/generators/sphere.js
• Change text point generation in src/generators/text.js
• Change morph timing behavior in src/utils/getMorphStrength.js

Local Development

npm install
npm run dev

Then open the local Vite URL, usually http://localhost:5173.

Build For npm

npm run build

This creates the publishable package files in dist/.

Publish To npm

npm login
npm publish --access public

If the package name is already taken on npm, change the name field in package.json first.

GitHub Publishing

If you want to make this available to others on GitHub:

cd /home/reyhan/Desktop/agripion/particle-morph-library
git init
git add .
git commit -m "feat: add particle morph library"
git branch -M main
git remote add origin <YOUR_GITHUB_REPO_URL>
git push -u origin main

Notes

• Nothing in this folder is wired into your existing project.
• The structure keeps rendering logic separate from the UI layer so it is easier to integrate with React, Next.js, or plain HTML later.
• three is a peer dependency, so consumers should install it in their own project.