Getting Started

Set up D3 UI in your React or Next.js project with Tailwind CSS and D3.js.

Prerequisites

Node.js 18+ and npm/pnpm
React project (Next.js recommended)
Tailwind CSS installed

Install Tailwind CSS

Follow the official Tailwind setup guide if you haven’t already.

Install D3.js

Installing d3

npm install d3

Add the primitives components

./components/primitives/Axis.tsx

"use client";
import { useEffect, useRef } from "react";
import * as d3 from "d3";
import { Axis as D3Axis } from "d3";

type Orient = "bottom" | "left" | "top" | "right";

interface AxisProps<Scale extends d3.AxisScale<any>> {
  scale: Scale;
  orient?: Orient;
  transform?: string;
  ticks?: number;
  tickFormat?: (d: any) => string; // override
}

export function Axis<Scale extends d3.AxisScale<any>>({
  scale,
  orient = "bottom",
  transform = "",
  ticks = 5,
  tickFormat,
}: AxisProps<Scale>) {
  const ref = useRef<SVGGElement>(null);

  useEffect(() => {
    let axisGenerator: D3Axis<any> =
      orient === "bottom" ? d3.axisBottom(scale) : d3.axisLeft(scale);

    if ("ticks" in axisGenerator) axisGenerator.ticks(ticks);

    if (tickFormat) {
      axisGenerator.tickFormat(tickFormat as any);
    } 

    d3.select(ref.current).call(axisGenerator as any);
  }, [scale, orient, ticks, tickFormat]);

  return <g ref={ref} transform={transform} />;
}

./components/primitives/Tooltip.tsx

"use client";
import { createContext, useContext, useRef, useState, ReactNode } from "react";
import { cn } from "../lib/utils";

type TooltipContextType = {
  show: (options: { content: string; title?: string; color?: string }, e: React.MouseEvent) => void;
  hide: () => void;
} | null;

const TooltipContext = createContext<TooltipContextType>(null);

export const useTooltip = () => {
  const context = useContext(TooltipContext);
  if (!context) {
    throw new Error("useTooltip must be used within a TooltipProvider");
  }
  return context;
};

interface TooltipProviderProps {
  children: ReactNode;
  className?: string;
  contentClassName?: string;
}

interface TooltipProps {
  children: (props: {
    show: (options: { content: string; title?: string; color?: string }, e: React.MouseEvent) => void;
    hide: () => void;
  }) => React.ReactNode;
  className?: string;
  contentClassName?: string;
}

export function TooltipProvider({ children, className, contentClassName }: TooltipProviderProps) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [visible, setVisible] = useState(false);
  const [tooltipData, setTooltipData] = useState<{ content: string; title?: string; color?: string }>({ content: "" });
  const [position, setPosition] = useState({ x: 0, y: 0 });

  const show = (options: { content: string; title?: string; color?: string }, e: React.MouseEvent) => {
    const rect = containerRef.current?.getBoundingClientRect();
    if (!rect) return;
    const x = e.clientX - rect.left;
    const y = e.clientY - rect.top;
    setTooltipData(options);
    setPosition({ x, y });
    setVisible(true);
  };

  const hide = () => setVisible(false);

  const value = { show, hide };

  return (
    <div ref={containerRef} className={cn("relative w-fit h-fit", className)}>
      <TooltipContext.Provider value={value}>
        {children}
      </TooltipContext.Provider>

      {visible && (
        <div
          className={cn(
            "absolute pointer-events-none border border-gray-200 bg-white text-gray-900 text-xs rounded-lg shadow-lg",
            "dark:border-slate-700 dark:bg-slate-800 dark:text-slate-50",
            "transition-opacity duration-150",
            contentClassName
          )}
          style={{
            top: position.y,
            left: position.x,
            transform: "translate(10px, -50%)",
            opacity: visible ? 1 : 0,
          }}
        >
          {(tooltipData.title || tooltipData.color) && (
            <div className="flex items-center gap-2 px-3 py-1.5">
              {tooltipData.color && (
                <div 
                  className="w-2 h-2 rounded-sm flex-shrink-0"
                  style={{ 
                    backgroundColor: tooltipData.color,
                    minWidth: '8px',
                    minHeight: '8px',
                  }}
                />
              )}
              {tooltipData.title && (
                <span className="font-medium whitespace-nowrap">{tooltipData.title}</span>
              )}
            </div>
          )}
          <div className="px-3 py-1.5">
            {tooltipData.content}
          </div>
        </div>
      )}
    </div>
  );
}

./components/primitives/Tooltip.tsx

import { cn } from "../lib/utils";

interface LegendItem {
  label: string;
  color: string;
}

interface LegendProps {
  className?: string;
  itemClassName?: string;
  items: LegendItem[];
}

export function Legend({ items, className, itemClassName }: LegendProps) {
  return (
    <div className={cn("flex flex-wrap gap-4 mt-4", className)}>
      {items.map((item) => (
        <div
          key={item.label}
          className={cn("flex items-center gap-2", itemClassName)}
        >
          <span
            className="block w-4 h-4 rounded-sm "
            style={{ backgroundColor: item.color }}
          ></span>
          <span className="text-sm">
            {item.label}
          </span>
        </div>
      ))}
    </div>
  );
}

Add Components

Copy any component you want from our docs into your project’s components folder:

src/
  components/
    charts/
      LineChart.tsx

Use the Component

import LineChart from "@/components/charts/LineChart";

const data = [
  { x: 0, y: 10 },
  { x: 1, y: 30 },
  { x: 2, y: 20 },
];

export default function Example() {
  return <LineChart data={data} />;
}

That’s it! You’re ready to use D3 UI components in your app.