Installation

npm install family-tree-viewer

Or via CDN (UMD bundle, no build step required):

<script src="https://unpkg.com/family-tree-viewer"></script>

Quick start

import { FamilyTreeViewer } from 'family-tree-viewer';

const viewer = new FamilyTreeViewer('#container', {
  theme: 'light',
  readonly: false,
  onSave: (gedcom) => localStorage.setItem('tree', gedcom),
});

// Load a GEDCOM file
const text = await fetch('family.ged').then(r => r.text());
viewer.loadGedcom(text);

// — or — load ancestors from WikiTree
await viewer.loadWikiTree('Einstein-1', { depth: 3 });

Constructor options

new FamilyTreeViewer(container, options?) — container is a CSS selector string or HTMLElement.

Option	Type	Default	Description
gedcom	string	—	Initial GEDCOM text to load on construction.
rootId	string	auto	GEDCOM @I…@ id of the root person for layout.
theme	'light' | 'dark'	'light'	Visual theme.
readonly	boolean	false	Hides all editing controls when true.
onSave	(gedcom: string) => void	—	Called after any edit with the serialised GEDCOM string.

Public methods

Method	Description
loadGedcom(text: string)	Parse and render a GEDCOM string. Replaces any previously loaded tree.
loadWikiTree(id, opts?) async	Fetch ancestors from WikiTree by profile key (e.g. 'Washington-1'). opts.depth (1–4, default 3) controls how many ancestor generations to retrieve.
getGedcom(): string	Serialise the current in-memory tree to a GEDCOM 5.5.1 string.
fitToScreen()	Pan and zoom to fit the entire tree in the container.
selectPerson(id: string)	Programmatically select a person by their GEDCOM id and open the side panel.
destroy()	Remove all event listeners and DOM nodes. Call before removing the container.

WikiTree integration

loadWikiTree calls the public WikiTree API (getAncestors action) directly from the browser — no server proxy required, as WikiTree supports CORS for public profiles.

• Only public WikiTree profiles can be accessed without authentication.
• The depth option controls ancestor generations (1–4). Larger values fetch exponentially more data.
• On failure a WikiTreeError is thrown with a descriptive message. Catch it to display user-facing errors.
• The resulting tree can be exported as GEDCOM via getGedcom(). IDs use the @W{n}@ format.

try {
  await viewer.loadWikiTree('Darwin-15', { depth: 2 });
} catch (err) {
  if (err.name === 'WikiTreeError') {
    console.error('WikiTree error:', err.message);
  }
}

GEDCOM support

Parser targets GEDCOM 5.5.1. Supported features:

• Individuals (INDI): name, sex, birth, death, notes, family links
• Families (FAM): husband, wife, children, marriage event
• Multi-line values via CONC / CONT continuation tags
• UTF-8 encoding (ANSEL files load with a console warning)

Not currently parsed: sources (SOUR), repositories, multimedia, custom tags (_XXX).

TypeScript types

All public types are re-exported from the package entry point:

import type { Individual, Family, EventRecord, Sex } from 'family-tree-viewer';

Type	Key fields
Individual	id, givenName, surname, sex, birth?, death?, familyAsChild?, familiesAsSpouse[]
Family	id, husbandId?, wifeId?, childIds[], marriage?
EventRecord	type, date?, year?, place?
Sex	'M' | 'F' | 'U'

License

Released under the AGPL-3.0 license. If you deploy this library as part of a network service, you must make the complete source code available to users of that service. See the LICENSE file for details.