Documentation

DepthText is a lightweight, dependency-free JavaScript library that creates smooth multi-layer 3D text with depth, parallax, and interactive rotation using pure CSS 3D transforms.

📚 How it work ?

Description du fonctionnement de DepthText

LIVE DEMO

Try Me! 🎯

📦 Installation

NPM / Yarn

    npm install depthtext
# or
yarn add depthtext
# or
pnpm add depthtext

CDN (Browser)

Add this script tag to your HTML:

    <script src="https://unpkg.com/depthtext@latest/dist/depthtext.global.js"></script>

💡 Tip

For production, pin to a specific version instead of @latest:

    https://unpkg.com/depthtext@1.1.0/dist/depthtext.global.js

ES Module Import

    import { DepthTextify, DepthTextInstance } from "depthtext";

⚡ Quick Start

The easiest way to use DepthText is via HTML data attributes. The library auto-initializes all elements with data-depth attributes.

HTML Example

    <h1 data-depth="1rem" data-depth-layers="10" data-depth-event="pointer">
  DepthText Rocks! 🚀
</h1>
LIVE DEMO

DepthText Rocks! 🚀

JavaScript Initialization (Optional)

If you need more control or want to initialize programmatically:

    import { DepthTextify } from "depthtext";

// Auto-init all elements with data-depth
DepthTextify();

// Or target specific selector
DepthTextify('.my-text', {
  depth: '2rem',
  layers: 15,
  event: 'pointer'
});

⚙️ Options Reference

Complete list of all configuration options for DepthText. Each option can be set via HTML data attributes or JavaScript.

OptionHTML AttributeTypeDefaultDescription
depthdata-depthstring"1rem"Total depth of the 3D effect. Accepts any CSS length unit (px, rem, em, etc.)
layersdata-depth-layersnumber10Number of layers to generate (1-40). More layers = smoother effect but lower performance.
direction v1.1data-depth-directionstring"both"Layer distribution direction: "both" (centered), "forwards", or "backwards"
eventdata-depth-eventstring"none"Interaction type: "none", "pointer", "scroll", "scrollX", or "scrollY"
eventRotationdata-depth-event-rotationstring"30deg"Maximum rotation angle for interactive events
eventDirectiondata-depth-eventdirectionstring"default"Rotation direction: "default" or "reverse"
fadedata-depth-fadebooleanfalseIf true, layers fade out as they go deeper
perspectivedata-depth-perspectivestring"500px"CSS perspective value for the 3D effect
addClass v1.1data-depth-add-classstring""Custom CSS class(es) to add to all layers. Space-separated for multiple classes.
engageddata-depth-engagedbooleantrueIf false, the effect is disabled but can be activated later
layerClassMap v1.2.0N/A (JS only)array[]Array of CSS class names to apply to individual layers by index. Enables unique styling per layer (e.g., different colors for each depth level).

Auto-Generated Layer Classes

Each layer automatically receives a depthtext-layer-N class (0-indexed), allowing precise CSS targeting:

    .depthtext-layer-0 { color: red; }
.depthtext-layer-1 { color: orange; }
.depthtext-layer-2 { color: yellow; }

Examples by Option

Direction Examples

Both

direction="both" (default)

Both
Forwards

direction="forwards"

Forward
Backwards

direction="backwards"

Backward

addClass Example

Apply custom CSS classes to all layers for advanced styling like gradients:

    <h1 
  data-depth="1.5rem" 
  data-depth-layers="12"
  data-depth-add-class="text-gradient my-custom-class"
>
  Styled Text
</h1>

layerClassMap Example v1.2.0

Apply different classes to individual layers for rainbow effects or unique styling per depth level:

    import { DepthTextInstance } from 'depthtext';

const element = document.querySelector('#rainbow-text');
new DepthTextInstance(element, {
  depth: '1.5rem',
  layers: 5,
  layerClassMap: ['layer-red', 'layer-orange', 'layer-yellow', 'layer-green', 'layer-blue']
});
  
    .layer-red { color: #ff0000; }
.layer-orange { color: #ff8800; }
.layer-yellow { color: #ffff00; }
.layer-green { color: #00ff00; }
.layer-blue { color: #0088ff; }

🔧 JavaScript API

For advanced use cases, you can use the JavaScript API directly:

DepthTextInstance Class

    import { DepthTextInstance } from "depthtext";

const element = document.querySelector('#my-text');
const instance = new DepthTextInstance(element, {
  layers: 15,
  depth: "2rem",
  event: "pointer",
  eventRotation: "45deg",
  fade: true,
  addClass: "custom-gradient"
});

// Later, if needed:
instance.destroy();

DepthTextify Function

    import { DepthTextify } from "depthtext";

// Initialize all [data-depth] elements
DepthTextify();

// Or with selector and options
DepthTextify('.my-selector', {
  depth: '3rem',
  layers: 20
});

Instance Methods

MethodDescription
instance.tilt(x, y)Manually apply tilt. x and y are values between -1 and 1.
instance.update(options) v1.2.0Dynamically update options without recreating the instance. Useful for responsive designs and interactive controls.
instance.destroy()Clean up the instance, remove layers, and restore original content.

update() Example v1.2.0

    const instance = new DepthTextInstance(element, { 
  depth: "1rem",
  event: "pointer" 
});

// Later, update options dynamically
instance.update({ 
  depth: "2rem", 
  event: "scroll",
  layers: 15
});

// Responsive: change depth on mobile
if (window.innerWidth < 768) {
  instance.update({ depth: "0.5rem", layers: 5 });
}

⚛️ Framework Integration

React / Next.js

    import { useEffect, useRef } from "react";
import { DepthTextInstance } from "depthtext";

export default function DepthComponent() {
  const textRef = useRef(null);

  useEffect(() => {
    if (!textRef.current) return;

    const dt = new DepthTextInstance(textRef.current, {
      layers: 10,
      depth: "1rem",
      event: "pointer",
    });

    return () => dt.destroy(); // Cleanup
  }, []);

  return <h1 ref={textRef}>DepthText in React</h1>;
}

Vue 3

    <script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { DepthTextInstance } from "depthtext";

const textRef = ref(null);
let dt = null;

onMounted(() => {
  if (textRef.value) {
    dt = new DepthTextInstance(textRef.value, {
      layers: 10,
      depth: "1rem"
    });
  }
});

onUnmounted(() => {
  if (dt) dt.destroy();
});
</script>

<template>
  <h1 ref="textRef">DepthText in Vue</h1>
</template>

🌐 Browser Support

DepthText uses standard CSS 3D transforms and is supported in all modern browsers.

  • ✅ Chrome
  • ✅ Firefox
  • ✅ Safari
  • ✅ Edge

🚀 Performance Tips

  • Layer Count: Keep layers under 20 for best performance on mobile.
  • Complexity: Avoid applying to very large blocks of text.
  • Events: pointer events are more expensive than scroll.

🔍 Troubleshooting