030 / D3.JS / NETWORK

D3 Force-Directed Network

Force-directed network with a settling physics simulation, labeled nodes, and automatic centering.

SPEC: #030
ENGINE: D3.js
FAMILY: Network
RENDERER: svg
STATUS: beta

Source GitHub

PLOTCN/REGISTRY/D3-FORCE-NETWORK/SOURCE

pnpm dlx shadcn@latest add @plotcn/d3-force-network

Checking public registry…

View local registry JSON

REGISTRY direct URL·ENGINE D3.js·FILES 1·DEPENDENCIES 3

Copied as source into your project (requires d3-force).

… × 340Container width

Measuring preview...

D3 · SVG · 0 × 340pxMotion enabled · ResizeObserver

Component Specifications

BEST FOR: D3 Force-Directed Network visual analytics and network category telemetry.
DATA MODEL: Normalized network records matching canonical dataShape.
INTERACTION: Static presentation
RESPONSIVE: Container-aware ResizeObserver
ANIMATION: Interpolated transitions
RUNTIME: D3.js svg

01 / Component Usage

Basic & Interactive Integration

Import D3ForceNetwork directly into your React client component. Provide an array of observations conforming to the data shape.

page.tsx

import { D3ForceNetwork } from "@/components/charts/d3/d3-force-network"

const data = [
  {
    "label": "Jan",
    "value": 186
  },
  {
    "label": "Feb",
    "value": 305
  },
  {
    "label": "Mar",
    "value": 237
  }
]

export default function ChartDemo() {
  return (
    <div className="w-full max-w-xl h-80">
      <D3ForceNetwork data={data} color="#10b981" />
    </div>
  )
}

Requires a client context ('use client') for DOM lifecycle and container measurement.

Expected ResultLive 220px

Container-aware width · 200px height

02 / Data Contract

Input Schema & Coordinates

Input data format for D3 Force-Directed Network. Records should provide required coordinates and metrics.

Chart data contract
Field	Type	Required	Meaning
`label`	`string`	Yes	Category label or horizontal axis timestamp
`value`	`number`	Yes	Metric numerical magnitude

Null / Missing Value Policy:

Missing values are gracefully handled or skipped depending on interpolation rules.

Coordinate Ordering Policy:

Records should follow monotonic sorting for sequential coordinate plots.

Example Observation Payload:

[
  {
    "label": "Jan",
    "value": 186
  },
  {
    "label": "Feb",
    "value": 305
  },
  {
    "label": "Mar",
    "value": 237
  }
]

03 / Component API & Styling

Props Reference & Interactive Prop Explorer

Inspect every component property, customize semantic color roles live with instant visual feedback, and copy production-ready code with active prop configurations.

Colors & Appearance Configuration

Customize primary, reference, or annotation series colors. Defaults derive from Plotcn theme tokens.

Generated Usage Code (Live Props):

<Chart
  data={data}
  xKey="date"
  seriesKey="value"
/>

Interactive Prop Preview Lab

colorstring

Primary theme stroke or fill color. Accepts CSS variables or color values.

Select value to preview live:#10b981

Active: color="#10b981"Default: "var(--chart-1, #10b981)"

All Properties (4)

Component properties
Property	Type	Default	Required	Description
dataReq	`Record<string, any>[]`	`—`	Yes	Array of structured observations or datum objects to visualize. Best for: Primary dataset
colorOpt	`string`	`"var(--chart-1, #10b981)"`	No	Primary theme stroke or fill color. Accepts CSS variables or color values. Best for: Theming and visual branding
heightOpt	`number \| string`	`320`	No	Container height in pixels or standard CSS dimension strings.
classNameOpt	`string`	`undefined`	No	Tailwind CSS classes or custom stylesheet class applied to container wrapper.

04 / Cookbook & States

Component Variants & Edge States

Production cookbooks showcasing configuration variants alongside verified handling of loading, empty data, and network error states.

D3 Force-Directed Network (Default)

Standard presentation with Plotcn dark theme tokens.

<D3ForceNetwork nodes={nodes} links={links} />

Lifecycle & Exception States

01. Loading State

Skeletons indicate runtime fetch or pending data queries.

02. Empty Data State

Handles empty collections ([]) gracefully without crashing.

03. Error State

Graceful failure banner when data source or script fails.

05 / Responsive Lab

Container-Driven Breakpoints

Scales gracefully according to container width, recalculating layout bounds.

Desktop

1100px+

Full horizontal scale and complete axis tick labeling.

Tablet

768px

Tighter margins with optimized coordinate grid spacing.

Mobile

390px

Compact labels and touch-friendly interaction.

Tablet Preview (768px Container Constraint)Auto-measuring

Mobile Preview (390px Container Constraint)Compact tap region

06 / Assistive Technology

Accessibility & Navigation Standards

Accessible visualization presenting D3 Force-Directed Network data with semantic contrast.

Semantic Role & Landmark

Container mounts as figure[role="region"] with explicit assistive label.

Color-Independent Legibility

Coordinate baselines and labels preserve data legibility regardless of color perception.

Screen Reader Summary

Embeds visually hidden summary (.sr-only) declaring: “D3 Force-Directed Network data visualization”

Reduced Motion Support

Suppresses transitions when user prefers reduced motion.

Keyboard Interaction Model

Keyboard interaction model
Key	Action
`Tab`	Focus chart container and navigate through interactive regions.

07 / Source Anatomy

Internal Architecture & File Dependencies

Source-first ownership model. Inspect the exact component call tree, dependencies, and full implementation below.

Component Architecture Call Tree

●D3ForceNetwork(Component Entry)

└──D3.js Engine Layer[svg]

Visualization calculations and rendering via D3.js.

Involved Source Files & Registry Assets

registry/d3/d3-force-network.tsx

Primary component source implementation.