Configuration

The configuration object controls every aspect of your particle text animation. This page documents all available options with examples.

Configuration Object

initParticleJS('#canvas', {
// Text & Display
text: 'ParticleText',
colors: ['#695aa6'],
fontSize: 100,
fontWeight: 'bold',
textAlign: 'center',

// Canvas Dimensions
width: 1200,
height: 400,

// Animation Control
autoAnimate: true,

// Particle Behavior
particleRadius: { xs: { base: 1, rand: 1 } },
explosionRadius: { xs: 50 },
friction: { base: 0.9, rand: 0.05 },

// Performance
maxParticles: 5000,
supportSlowBrowsers: false,
renderTimeThreshold: 15,

// Interaction
trackCursorOnlyInsideCanvas: false,

// Callbacks
slowBrowserDetected: function() {}
});

Text & Display Options

text

Type: String Default: Value from data-text attribute Required: Yes (either config or data-text)

The text to display as particles. Overrides the data-text attribute if both are specified.

initParticleJS('#canvas', {
text: 'ParticleText.js',
colors: ['#695aa6']
});

Custom Text

colors

Type: String | Array<String> | Array<Object> Default: [{ color: '#000000', weight: 1 }] Format: 6-digit hex color (#RRGGBB)

Colors are assigned to particles based on weights. Use a single color for uniformity, multiple colors for variety, or weighted colors for controlled distribution.

Basic Usage (String Format)

// Single color (provide as array)
colors: ['#FF6B6B']

// Multiple colors (equal distribution)
colors: ['#695aa6', '#8b7bb8', '#a89bc9']

// Single string (auto-converted to array)
colors: '#FF6B6B'

Weighted Colors (Object Format)

Control the color distribution by specifying weights. Higher weights mean more particles with that color.

// Weighted color distribution
colors: [
{ color: '#FF6B6B', weight: 5 },  // 5x more red particles
{ color: '#4ECDC4', weight: 2 },  // 2x more cyan particles
{ color: '#695aa6', weight: 1 }   // baseline purple particles
]

// Mix formats (strings default to weight: 1)
colors: [
{ color: '#FF6B6B', weight: 3 },
'#4ECDC4',  // Automatically gets weight: 1
'#695aa6'   // Automatically gets weight: 1
]

Weight Rules:

• Must be a positive integer (no decimals, no zero, no negatives)
• Default weight is 1 if not specified
• Relative to other weights (weight: 3 means 3x more than weight: 1)
• Configuration errors will show a browser alert

// ✅ Valid weights
colors: [
{ color: '#FF0000', weight: 1 },
{ color: '#00FF00', weight: 10 },
{ color: '#0000FF', weight: 100 }
]

// ❌ Invalid - will show alert and throw error
colors: [
{ color: '#FF0000', weight: 0 },      // Zero not allowed
{ color: '#00FF00', weight: -5 },     // Negative not allowed
{ color: '#0000FF', weight: 2.5 }     // Decimals not allowed
]

Validation: Colors must be in 6-digit hex format. #RGB shorthand is not supported.

// ✅ Valid
colors: ['#FF6B6B', '#4ECDC4']
colors: [{ color: '#FF6B6B', weight: 3 }]

// ❌ Invalid - will throw error
colors: ['#F6B', 'red', 'rgb(255,0,0)']
colors: [{ color: '#F6B', weight: 1 }]

Equal Distribution

Weighted Distribution (Red: 80%, Others: 5% each)

fontSize

Type: Number Default: canvas.height / 4 Unit: Pixels

Size of the text in pixels.

// Small text (40px)
fontSize: 40

// Medium text (100px)
fontSize: 100

// Large text (200px)
fontSize: 200

Tip: Canvas height should be at least 1.5× the font size to prevent clipping.

fontWeight

Type: String Default: 'bold' Supported: 'bold' only

Text weight. Currently only bold is supported.

fontWeight: 'bold'  // Only supported value

textAlign

Type: String Default: 'center' Supported: 'center' only

Text alignment. Currently only center alignment is supported.

textAlign: 'center'  // Only supported value

Canvas Dimensions

width

Type: Number Default: Canvas element width attribute Unit: Pixels

Width of the canvas. Can be set via HTML attribute or configuration.

// Via configuration
initParticleJS('#canvas', {
width: 1200,
colors: ['#695aa6']
});

// Via HTML attribute (recommended)
<canvas width="1200"></canvas>

height

Type: Number Default: Canvas element height attribute Unit: Pixels

Height of the canvas.

// Via configuration
initParticleJS('#canvas', {
height: 400,
colors: ['#695aa6']
});

// Via HTML attribute (recommended)
<canvas height="400"></canvas>

Best Practice: Set dimensions as HTML attributes for better initial rendering:

<canvas id="canvas" width="1200" height="400" data-text="Hello"></canvas>

Animation Control

autoAnimate

Type: Boolean Default: true

Whether to start animation automatically on initialization.

// Auto-start (default)
const particle = initParticleJS('#canvas', {
autoAnimate: true,
colors: ['#695aa6']
});

// Manual start
const particle = initParticleJS('#canvas', {
autoAnimate: false,
colors: ['#695aa6']
});

// Start later
document.getElementById('btn').onclick = () => {
particle.startAnimation();
};

Particle Behavior

particleRadius

Type: Object | Function Default: Responsive object with breakpoint values

Controls the radius of individual particles.

As Object (Responsive)

particleRadius: {
xxxs: { base: 1, rand: 1 },  // Mobile: 1-2px
xs: { base: 1, rand: 1 },    // Small: 1-2px
lg: { base: 1, rand: 1 }     // Large: 1-2px
}

• base: Minimum radius in pixels
• rand: Random addition (final radius = base + random(0, rand))
• Each breakpoint cascades to larger breakpoints unless overridden

As Function

particleRadius: function() {
// Custom logic for each particle
return Math.random() * 3 + 2;  // 2-5px
}

explosionRadius

Type: Object | Function Default: Responsive values from 30px (mobile) to 100px (large screens) Unit: Pixels

Distance from cursor where particles explode away.

As Object (Responsive)

explosionRadius: {
xxxs: 30,   // Small on mobile
xxs: 40,    // Mobile
xs: 50,     // Mobile/tablet
sm: 60,     // Tablet/small desktop
md: 70,     // Desktop
lg: 75,     // Large desktop
xl: 80,     // Extra large
xxl: 90,    // Ultra-wide
xxxl: 100   // 4K+ displays
}

Small Explosion Radius (50px)

As Function

explosionRadius: function() {
// Dynamic explosion radius
return window.innerWidth < 768 ? 30 : 100;
}

friction

Type: Object | Function Default: { base: 0.9, rand: 0.05 } Range: 0-1 (lower = faster movement)

Controls how quickly particles return to their original position.

As Object

friction: {
base: 0.9,   // Base friction
rand: 0.05   // Random variation
}
// Final friction: 0.9 to 0.95

• High friction (0.95-0.99): Slow, smooth return
• Medium friction (0.85-0.95): Balanced (default)
• Low friction (0.70-0.85): Fast, bouncy return

// Slow, smooth animation
friction: { base: 0.95, rand: 0.03 }

// Fast, bouncy animation
friction: { base: 0.75, rand: 0.05 }

As Function

friction: function() {
return Math.random() * 0.1 + 0.85;
}

Performance Options

maxParticles

Type: Number Default: 5000

Maximum number of particles to render. Limits performance impact on complex text.

// Low particle count (faster)
maxParticles: 500

// Default
maxParticles: 5000

// High particle count (detailed but slower)
maxParticles: 10000

Tip: Lower values improve performance on mobile devices.

supportSlowBrowsers

Type: Boolean Default: false

Enable automatic performance optimization for slow browsers.

supportSlowBrowsers: true

When enabled:

• Monitors initial render time
• Reduces quality/particles if slow
• Scales canvas to maintain appearance
• Triggers slowBrowserDetected callback

renderTimeThreshold

Type: Number Default: 15 Unit: Milliseconds

Threshold for detecting slow browsers. For smooth 60fps, each frame should render in ≤15ms.

renderTimeThreshold: 15  // 60fps target

Interaction Options

trackCursorOnlyInsideCanvas

Type: Boolean Default: false

Controls whether particles react to cursor position only when inside canvas.

// Track cursor anywhere (default)
trackCursorOnlyInsideCanvas: false

// Only track inside canvas
trackCursorOnlyInsideCanvas: true

When to use true:

• Multiple canvases on same page
• Clear interaction boundaries desired
• Canvas in sidebar/widget

When to use false (default):

• Single canvas (hero section)
• Smoother experience desired
• Full-page effects

Callbacks

slowBrowserDetected

Type: Function Default: function() {}

Called when a slow browser is detected (requires supportSlowBrowsers: true).

slowBrowserDetected: function() {
console.warn('Slow browser detected - reducing quality');
// Show message to user
document.getElementById('warning').style.display = 'block';
}

Breakpoint Reference

Valid breakpoint keys for responsive configuration:

Breakpoint	Width Range
xxxs	0px - 320px
xxs	320px - 375px
xs	375px - 768px
sm	768px - 1024px
md	1024px - 1440px
lg	1440px - 2560px
xl	2560px - 3440px
xxl	3440px - 3840px
xxxl	3840px+

See Breakpoint System for detailed usage.

Complete Example

initParticleJS('#canvas', {
// Text
text: 'ParticleText',
colors: ['#695aa6', '#8b7bb8', '#a89bc9'],
fontSize: 100,
fontWeight: 'bold',
textAlign: 'center',

// Canvas
width: 1200,
height: 400,

// Animation
autoAnimate: true,

// Particles (responsive)
particleRadius: {
  xs: { base: 1, rand: 1 },
  lg: { base: 1, rand: 1 }
},

// Explosion (responsive)
explosionRadius: {
  xs: 20,
  sm: 50,
  lg: 75,
  xxl: 150
},

// Friction
friction: {
  base: 0.9,
  rand: 0.05
},

// Performance
maxParticles: 5000,
supportSlowBrowsers: true,
renderTimeThreshold: 15,

// Interaction
trackCursorOnlyInsideCanvas: false,

// Callbacks
slowBrowserDetected: function() {
  console.warn('Performance optimization enabled');
}
});

Next Steps

• Methods - Control animation programmatically
• Properties - Access animation state
• Examples - See configurations in action
• Breakpoint System - Master responsive configs