Documentation

Everything you need to install, configure, and use Reactree.js in your React application.

Installation

Install the package from npm:

bash

npm install reactreejs

npm install reactreejs

Then install peer dependencies if they are not already present in your project:

bash

npm install react react-dom

npm install react react-dom

Supported peer versions: React 18 and React 19.

Quick start

tsx

import { Reactree } from 'reactreejs';
import 'reactreejs/style.css';

export default function App() {
  const newick = '((A:0.1,B:0.2):0.3,(C:0.4,D:0.1):0.2);';
  return <Reactree newick={newick} />;
}

import { Reactree } from 'reactreejs';
import 'reactreejs/style.css';

export default function App() {
  const newick = '((A:0.1,B:0.2):0.3,(C:0.4,D:0.1):0.2);';
  return <Reactree newick={newick} />;
}

The stylesheet import is required — see CSS import below.

With a sequence alignment

Pass a multi-FASTA string to enable the alignment panel. An Alignment toggle button will appear in the toolbar.

tsx

import { Reactree } from 'reactreejs';
import 'reactreejs/style.css';

const newick = '((Homo_sapiens:0.09,Anopheles:0.36):0.07,Mimivirus:1.22);';

const fasta = `
>Homo_sapiens
MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSY
>Anopheles
MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDS-
>Mimivirus
----KLVVVGAGGVGKSALTIQL-QNHFVDEYDPTIEDS-
`.trim();

export default function App() {
  return <Reactree newick={newick} fasta={fasta} defaultHeight={600} />;
}

import { Reactree } from 'reactreejs';
import 'reactreejs/style.css';

const newick = '((Homo_sapiens:0.09,Anopheles:0.36):0.07,Mimivirus:1.22);';

const fasta = `
>Homo_sapiens
MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSY
>Anopheles
MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDS-
>Mimivirus
----KLVVVGAGGVGKSALTIQL-QNHFVDEYDPTIEDS-
`.trim();

export default function App() {
  return <Reactree newick={newick} fasta={fasta} defaultHeight={600} />;
}

CSS import

The component stylesheet must be imported explicitly. Without it, the layout, spacing, and theming will not work:

import 'reactreejs/style.css';

import 'reactreejs/style.css';

Import it once, at the top level of your application — for example in main.tsx, _app.tsx, or your root layout. Do not import it more than once.

Props

Prop	Type	Required	Default	Description
`newick`	`string`	Yes	—	Newick tree string. Supports branch lengths and internal bootstrap labels.
`defaultHeight`	`number`	No	`520`	Initial viewer height in pixels. The user can resize at runtime via the drag handle at the bottom of the component.
`fasta`	`string`	No	—	Multi-FASTA sequence string. Enables the alignment panel toggle. Sequences are matched to leaf names by case-insensitive, underscore-normalised lookup.

Dark mode

Reactree.js reads the data-theme="dark" attribute on <html> and reacts to changes in real time via a MutationObserver. No context provider or additional configuration is needed.

Enable dark mode

document.documentElement.setAttribute('data-theme', 'dark');

document.documentElement.setAttribute('data-theme', 'dark');

Return to light mode

document.documentElement.removeAttribute('data-theme');
// or:
document.documentElement.setAttribute('data-theme', 'light');

document.documentElement.removeAttribute('data-theme');
// or:
document.documentElement.setAttribute('data-theme', 'light');

React toggle example

tsx

function ThemeToggle() {
  const [dark, setDark] = React.useState(false);

  function toggle() {
    const next = !dark;
    setDark(next);
    if (next) {
      document.documentElement.setAttribute('data-theme', 'dark');
    } else {
      document.documentElement.removeAttribute('data-theme');
    }
  }

  return <button onClick={toggle}>{dark ? 'Light' : 'Dark'} mode</button>;
}

function ThemeToggle() {
  const [dark, setDark] = React.useState(false);

  function toggle() {
    const next = !dark;
    setDark(next);
    if (next) {
      document.documentElement.setAttribute('data-theme', 'dark');
    } else {
      document.documentElement.removeAttribute('data-theme');
    }
  }

  return <button onClick={toggle}>{dark ? 'Light' : 'Dark'} mode</button>;
}

Respect OS preference on first load

if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.setAttribute('data-theme', 'dark');
}

if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.setAttribute('data-theme', 'dark');
}

Theming

All visual tokens are exposed as CSS custom properties. Import reactreejs/style.css, then override whatever you need in your own stylesheet:

css

/* your-app.css — loaded after reactreejs/style.css */
:root {
  --clr-primary-a0: #7c3aed;  /* accent — buttons, highlights */
  --clr-surface-a0: #fafaf9;  /* main background */
  --font-family: 'Inter', sans-serif;
}

/* Override dark mode tokens independently */
[data-theme='dark'] {
  --clr-primary-a0: #a78bfa;
  --clr-surface-a0: #020617;
}

/* your-app.css — loaded after reactreejs/style.css */
:root {
  --clr-primary-a0: #7c3aed;  /* accent — buttons, highlights */
  --clr-surface-a0: #fafaf9;  /* main background */
  --font-family: 'Inter', sans-serif;
}

/* Override dark mode tokens independently */
[data-theme='dark'] {
  --clr-primary-a0: #a78bfa;
  --clr-surface-a0: #020617;
}

Key tokens

Variable	Light default	Dark default	Role
`--clr-primary-a0`	`#0071f2`	`#3b82f6`	Accent — buttons, active states
`--clr-surface-a0`	`#ffffff`	`#0f172a`	Main background
`--clr-surface-a10`	`#f8fafc`	`#1e293b`	Secondary surface
`--clr-surface-a20`	`#f1f5f9`	`#334155`	Hover / tertiary surface
`--clr-text-primary`	`#0f172a`	`#f8fafc`	Primary text
`--clr-text-secondary`	`#475569`	`#94a3b8`	Secondary / muted text
`--clr-border`	`#e2e8f0`	`#334155`	Borders and dividers
`--clr-input-bg`	`#ffffff`	`#1e293b`	Input field backgrounds
`--font-family`	`'Segoe UI', …`	`(same)`	UI font — toolbar, labels

SSR / Next.js

Reactree.js uses D3, the Canvas API, and document/window directly. It is not compatible with server-side rendering as-is. Use a dynamic import with ssr: false:

tsx

import dynamic from 'next/dynamic';

const Reactree = dynamic(
  () => import('reactreejs').then(m => m.Reactree),
  { ssr: false }
);

export default function Page() {
  return <Reactree newick="((A:0.1,B:0.2):0.3,C:0.4);" />;
}

import dynamic from 'next/dynamic';

const Reactree = dynamic(
  () => import('reactreejs').then(m => m.Reactree),
  { ssr: false }
);

export default function Page() {
  return <Reactree newick="((A:0.1,B:0.2):0.3,C:0.4);" />;
}

Newick format

The parser accepts standard Newick with optional branch lengths and optional internal node labels:

text

((A:0.1,B:0.2):0.3,(C:0.4,D:0.1):0.2);        // branch lengths
((A,B)90,(C,D)85);                               // bootstrap values
((A:0.1,B:0.2)90:0.3,(C:0.4,D:0.1)85:0.2);     // both
(A,B,C);                                         // bare labels, no lengths

((A:0.1,B:0.2):0.3,(C:0.4,D:0.1):0.2);        // branch lengths
((A,B)90,(C,D)85);                               // bootstrap values
((A:0.1,B:0.2)90:0.3,(C:0.4,D:0.1)85:0.2);     // both
(A,B,C);                                         // bare labels, no lengths

The trailing semicolon is optional. Internal node labels that parse as numbers in the range [0, 100] are treated as bootstrap support values and displayed when the Bootstrap label mode is active.

FASTA matching

Leaf names are matched to FASTA headers by a two-step lookup:

Exact match after normalising underscores to spaces and lower-casing both sides.
Partial match — if no exact match is found, the first header that contains the leaf name (or vice versa) is used.

Leaves with no matching sequence are shown in the tree normally; their alignment row is simply empty.

TypeScript

import type { ReactreeProps } from 'reactreejs';

// The component prop type:
// {
//   newick: string;
//   defaultHeight?: number;
//   fasta?: string;
// }

import type { ReactreeProps } from 'reactreejs';

// The component prop type:
// {
//   newick: string;
//   defaultHeight?: number;
//   fasta?: string;
// }

Notes

Client-side only. D3, Canvas API, and document/window are accessed at render time. Use dynamic with { ssr: false } in SSR environments.
Resizing. The viewer height can be changed at runtime by dragging the resize grip at the bottom of the component. defaultHeight sets only the initial value.
Undo history. Reroot, flip, swap, and ladderize operations are stored in a local history. Ctrl+Z / ⌘Z undoes the last operation. Reset clears to the original tree.
Browser support. Modern evergreen browsers. Requires ES2020, SVG and Canvas API. Not tested in Internet Explorer.