plucked text.md

Plucked Text

A headline sitting on a string you can pluck, strum and let ring, built with React and real string physics.

Installation

npx shadcn@latest add @kokonutui/plucked-text

Props

Prop Type Default Description
text? string "Good vibrations" The line of text that sits on the string. Keep it to one line.
className? string Extra classes for the root element.
tension? number 1 How taut the string is. Higher rings faster and settles sooner.
strum? boolean true Strum the string when the cursor sweeps across it, not only on drag.

Source

"use client";

/**
 * @author: @dorianbaffier
 * @description: Plucked Text
 * @version: 1.0.0
 * @date: 2026-10-14
 * @license: MIT
 * @website: https://kokonutui.com
 * @github: https://github.com/kokonut-labs/kokonutui
 */

import { useEffect, useRef } from "react";
import { cn } from "@/lib/utils";

export interface PluckedTextProps {
  /** The line of text that sits on the string. Keep it to one line. */
  text?: string;
  className?: string;
  /** How taut the string is. Higher rings faster and settles sooner. */
  tension?: number;
  /** Strum the string when the cursor sweeps across it, not only on drag. */
  strum?: boolean;
}

...

export default function PluckedText({
  text = "Good vibrations",
  className,
  tension = 1,
  strum = true,
}: PluckedTextProps) {
  const stageRef = useRef<HTMLDivElement>(null);
  const lettersRef = useRef<HTMLSpanElement>(null);
  const svgRef = useRef<SVGSVGElement>(null);
  const pathRef = useRef<SVGPathElement>(null);
  const ghostRef = useRef<SVGPathElement>(null);

useEffect(() => {
    // Implementation details...
  }, [text, tension, strum]);

return (
    <div className={cn("@container flex w-full justify-center", className)}>
      <div
        className="group/pluck relative cursor-grab touch-none select-none px-[0.5em] py-[0.7em] font-semibold text-[clamp(2rem,11cqi,6rem)] text-zinc-900 leading-none tracking-tight data-[grabbing]:cursor-grabbing dark:text-zinc-100"
        ref={stageRef}
      >
        <span className="sr-only">{text}</span>
        <span
          aria-hidden="true"
          className="relative block whitespace-pre"
          ref={lettersRef}
        >
          {Array.from(text).map((char, index) => (
            <span
              className="inline-block origin-[50%_100%] will-change-transform"
              key={index}
            >
              {char}
            </span>
          ))}
          <span className="inline-block h-0 w-0" />
        </span>
        <svg
          aria-hidden="true"
          className="pointer-events-none absolute left-[0.25em] h-px w-[calc(100%-0.5em)] overflow-visible text-zinc-400 dark:text-zinc-600"
          ref={svgRef}
          style={{ top: "var(--pluck-baseline, 1.56em)" }}
        >
          <path
            className="opacity-30"
            fill="none"
            ref={ghostRef}
            stroke="currentColor"
            strokeLinecap="round"
            strokeWidth={1.5}
          />
          <path
            fill="none"
            ref={pathRef}
            stroke="currentColor"
            strokeLinecap="round"
            strokeWidth={1.5}
          />
        </svg>
        <span
          aria-hidden="true"
          className="pointer-events-none absolute left-[0.25em] size-[0.12em] -translate-x-1/2 -translate-y-1/2 rounded-full bg-zinc-400 dark:bg-zinc-600"
          style={{ top: "var(--pluck-baseline, 1.56em)" }}
        />
        <span
          aria-hidden="true"
          className="pointer-events-none absolute right-[0.25em] size-[0.12em] translate-x-1/2 -translate-y-1/2 rounded-full bg-zinc-400 dark:bg-zinc-600"
          style={{ top: "var(--pluck-baseline, 1.56em)" }}
        />
      </div>
    </div>
  );
}