https://github.com/magicsunday/webtrees-fan-chart
SVG ancestor fan chart module for the webtrees genealogy application — interactive D3.js visualization with zoom, export and up to 10 generations.
https://github.com/magicsunday/webtrees-fan-chart
ancestors chart d3 d3js data-visualization family-tree fan-chart genealogy module svg visualization webtrees webtrees-module
Last synced: 6 days ago
JSON representation
SVG ancestor fan chart module for the webtrees genealogy application — interactive D3.js visualization with zoom, export and up to 10 generations.
- Host: GitHub
- URL: https://github.com/magicsunday/webtrees-fan-chart
- Owner: magicsunday
- License: gpl-3.0
- Created: 2017-01-26T10:23:22.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2026-06-04T04:40:43.000Z (9 days ago)
- Last Synced: 2026-06-04T06:20:21.740Z (9 days ago)
- Topics: ancestors, chart, d3, d3js, data-visualization, family-tree, fan-chart, genealogy, module, svg, visualization, webtrees, webtrees-module
- Language: JavaScript
- Homepage:
- Size: 8.27 MB
- Stars: 67
- Watchers: 9
- Forks: 21
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/magicsunday/webtrees-fan-chart/releases/latest)
[](https://github.com/magicsunday/webtrees-fan-chart/blob/main/LICENSE)
[](https://github.com/magicsunday/webtrees-fan-chart/actions/workflows/ci.yml)
* [Fan chart](#fan-chart)
* [Installation](#installation)
* [Manual installation](#manual-installation)
* [Using Composer](#using-composer)
* [Using Git](#using-git)
* [Update](#update)
* [Configuration](#configuration)
* [Usage](#usage)
* [Troubleshooting](#troubleshooting)
* [Development](#development)
# Fan chart
This module provides an interactive SVG ancestor fan chart for the [webtrees](https://www.webtrees.net) genealogy application.
Click on any ancestor to re-center the chart on that person. Right-click to open a tooltip with detailed
dates, places, and images.
## Installation
Requires **webtrees 2.2** and **PHP 8.3** or later.
### Manual installation
> [!IMPORTANT]
> **Download the right `.zip` file.** Each [GitHub release](https://github.com/magicsunday/webtrees-fan-chart/releases/latest) page lists two kinds of archive:
>
> - ✅ **`webtrees-fan-chart.zip`** — listed under **Assets** at the bottom of the release. This is the install-ready archive: it bundles the required `vendor/` dependencies (such as `webtrees-module-base`).
> - ❌ **"Source code (zip)" / `webtrees-fan-chart-.zip`** — auto-generated by GitHub from the tag. This is the raw source *without* bundled dependencies. Uploading it to `modules_v4/` will fail with `Trait/Interface "MagicSunday\Webtrees\ModuleBase\…" not found` (or `ModuleAssetUrlInterface not found`).
>
> **Always pick the asset zip, never "Source code (zip)".**
> [!IMPORTANT]
> **If a previous version of this module is already installed:** delete the entire `modules_v4/webtrees-fan-chart` folder *before* extracting the new ZIP. Extracting on top of an existing folder leaves stale files behind that can clash with the new release — a common cause of `Interface … not found` errors right after an update.
1. Open the [latest release](https://github.com/magicsunday/webtrees-fan-chart/releases/latest) page.
2. Under **Assets**, download `webtrees-fan-chart.zip`.
3. Upload the `.zip` file to your web server.
4. Unzip the package into your `modules_v4` directory.
5. Rename the folder to `webtrees-fan-chart`.
You should now see a `modules_v4/webtrees-fan-chart` directory containing the module files.
### Using Composer
Run the following command from the root of your webtrees installation:
```shell
composer require magicsunday/webtrees-fan-chart --update-no-dev
```
The module will automatically install into the `modules_v4` directory.
To remove the module:
```shell
composer remove magicsunday/webtrees-fan-chart --update-no-dev
```
If you are using the development version of webtrees (`main` branch):
```shell
composer require magicsunday/webtrees-fan-chart:dev-main --update-no-dev
```
### Using Git
Clone the repository into your `modules_v4` directory (a *Code → Download ZIP* of
the source works the same way):
```shell
git clone https://github.com/magicsunday/webtrees-fan-chart.git modules_v4/webtrees-fan-chart
```
A source checkout contains the module code **only** — it does **not** include the
shared `webtrees-module-base` library, so on its own it fails with
`Trait "MagicSunday\Webtrees\ModuleBase\…" not found`. Supply that library in one
of two ways:
**Way A — drop-in (no code change).** Download
[`webtrees-module-base`](https://github.com/magicsunday/webtrees-module-base) and
copy its `src/` to the location this module's `module.php` already expects:
```text
modules_v4/webtrees-fan-chart/vendor/magicsunday/webtrees-module-base/src/…
```
**Way B — shared copy (one edit).** Place `webtrees-module-base` next to this
module in `modules_v4/` (rename the extracted folder to `webtrees-module-base`),
then point this module's `module.php` at it. A single shared copy then serves
every magicsunday module installed this way:
```php
// modules_v4/webtrees-fan-chart/module.php
$loader->addPsr4(
'MagicSunday\\Webtrees\\ModuleBase\\',
__DIR__ . '/../webtrees-module-base/src'
);
```
> [!IMPORTANT]
> Both ways are overwritten by every module update, so you must redo them after
> each upgrade. For a maintenance-free install **without** Composer, use the
> [asset zip](#manual-installation) (it bundles all dependencies). Inside a
> **Composer-managed** webtrees, prefer `composer require magicsunday/webtrees-fan-chart:dev-main`
> — see [Using Composer](#using-composer).
## Update
To update to the latest version:
- **Manual installation**: From the [latest release](https://github.com/magicsunday/webtrees-fan-chart/releases/latest) **Assets** section, download `webtrees-fan-chart.zip` (not "Source code (zip)"), **delete the old `modules_v4/webtrees-fan-chart` folder first**, and extract the new one. Extracting on top of an existing folder leaves stale files behind that can clash with the new release (a common cause of `Interface … not found` errors after an update).
- **Composer**: Run `composer update magicsunday/webtrees-fan-chart --update-no-dev`.
- **Git**: Run `git pull` inside the `modules_v4/webtrees-fan-chart` directory, then re-apply your source step (see [Using Git](#using-git)).
## Configuration
1. Go to the **Control Panel** (admin section) of your webtrees installation.
2. Scroll down to the **Modules** section and click on **Charts** (under Genealogy).
3. Enable the **Fan chart** module. Optionally disable the built-in fan chart to avoid confusion.
4. Click **Save**.
## Usage
Open the **Charts** menu on any individual page and select **Fan chart**.
The form at the top lets you choose the starting person, fan size (180-360 degrees), and number of
generations (2-10).
Click **Show more options** to access additional settings:
| Option | Description |
|--------|-------------|
| **Display mode** | Choose between "Show names and images", "Show names only", or "Show images only". Images are only shown if the arc segment is wide enough. |
| **Show descendants** | Shows partners and children as arcs below the ancestor section. The fan size is limited to 180-270 degrees when enabled. |
| **Hide empty segments** | Hides chart segments for missing ancestors. |
| **Show places** | Displays birth and death places in the chart arcs where space allows. For descendants with many children, places are automatically suppressed. Choose the level of detail (full name or lowest 1-3 hierarchy levels). |
| **Show parent marriage dates** | Displays marriage dates in a narrow arc between each pair of parent arcs. When descendants are enabled, also shows the marriage date between the central person and their partners. |
| **Show family colors** | Colors arcs by family branch. Paternal and maternal base colors are configurable via color pickers. |
| **Birth and death date precision** | Show full birth and death dates (DD.MM.YYYY) for early generations. Outer generations use a compact year-only format. Marriage dates switch to year-only from generation 7 and are hidden from generation 9. Descendants with narrow arcs automatically use a compact format. |
| **Number of inner levels** | Controls how many generations use the wider inner-arc layout with text along the arc path. |
| **Font size** | Scales the text size (50-150%). |
**Interacting with the chart:**
| Action | Effect |
|--------|--------|
| Click on a person | Re-centers the chart on that person |
| Right-click on a person | Opens a detailed tooltip with dates, places, and image |
| Ctrl + scroll | Zoom in/out |
| Click and drag | Move the chart |
| Click center button | Reset view to center |
| Fullscreen button | Toggle fullscreen mode |
| PNG / SVG buttons | Export the chart as an image file |
## Troubleshooting
**Fatal error after a manual installation or update: `Trait/Interface "MagicSunday\Webtrees\ModuleBase\…" not found` (or `ModuleAssetUrlInterface not found`)**
- You probably downloaded the GitHub-generated **"Source code (zip)"** (or used *Code → Download ZIP*) instead of the install-ready asset **`webtrees-fan-chart.zip`**. The asset bundles the required `vendor/` dependencies; the source zip does not. Open the [latest release](https://github.com/magicsunday/webtrees-fan-chart/releases/latest), scroll to **Assets**, download `webtrees-fan-chart.zip`, and re-extract.
- If you used the asset zip, make sure you **deleted the previous `modules_v4/webtrees-fan-chart` folder before extracting**. Stale files from an older version can shadow the new bundled vendor code and produce the same error.
**The chart does not appear / shows an error**
- Make sure the module is enabled in the Control Panel under Modules > Charts.
- Check that your PHP version is 8.3 or later.
- Clear your browser cache and reload the page.
**Images are not displayed**
- Ensure "Show highlight images" is enabled in the tree preferences (Control Panel > Family trees > Preferences).
- Verify that media files are uploaded and linked to individuals.
**Places are not shown**
- Enable "Show places" in the chart options (under "Show more options").
- Make sure the individuals have PLAC fields in their GEDCOM records.
## Development
This section is for developers who want to contribute to the module.
### Building JavaScript
Using Docker (no local Node.js required):
```shell
make install
make build
```
Using local Node.js:
```shell
npm install
npm run prepare
```
### Running tests
```shell
# JavaScript tests
npm test
# Full PHP + JS quality check
composer update
composer ci:test
```