{"id":21366870,"url":"https://github.com/acdh-oeaw/network-visualisation","last_synced_at":"2025-07-07T05:34:25.990Z","repository":{"id":41132232,"uuid":"197344643","full_name":"acdh-oeaw/network-visualisation","owner":"acdh-oeaw","description":null,"archived":false,"fork":false,"pushed_at":"2022-07-19T12:13:45.000Z","size":988,"stargazers_count":7,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-06T07:19:29.829Z","etag":null,"topics":["network-visualization"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acdh-oeaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-17T08:07:53.000Z","updated_at":"2022-12-15T15:23:25.000Z","dependencies_parsed_at":"2022-07-14T23:30:37.538Z","dependency_job_id":null,"html_url":"https://github.com/acdh-oeaw/network-visualisation","commit_stats":null,"previous_names":["acdh-oeaw/network-visualization"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/acdh-oeaw/network-visualisation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fnetwork-visualisation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fnetwork-visualisation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fnetwork-visualisation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fnetwork-visualisation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acdh-oeaw","download_url":"https://codeload.github.com/acdh-oeaw/network-visualisation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fnetwork-visualisation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263863211,"owners_count":23521577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["network-visualization"],"created_at":"2024-11-22T07:16:45.075Z","updated_at":"2025-07-07T05:34:25.971Z","avatar_url":"https://github.com/acdh-oeaw.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# network-visualization\n\nThis is a React component to visualize graph data in 2D and 3D. It is based on\n[`force-graph`](https://github.com/vasturiano/force-graph) and\n[`3d-force-graph`](https://github.com/vasturiano/3d-force-graph), which use\n[`d3-force`](https://github.com/d3/d3-force) and\n[`d3-force-3d`](https://github.com/vasturiano/d3-force-3d) for the simulation.\n\n## How to install\n\nInstall it as a package from NPM:\n\n```sh\nnpm i @acdh/network-visualization\n```\n\nYou can also include the UMD build in a `script` tag, and access the components\non the `NetworkVisualization` global:\n\n```html\n\u003cscript src=\"network-visualization.umd.js\"\u003e\u003c/script\u003e\n```\n\nThe UMD build is also available via CDN:\n\n```html\n\u003cscript src=\"https://unpkg.com/@acdh/network-visualization@0/lib/network-visualization.umd.js\"\u003e\u003c/script\u003e\n```\n\nWhen using the UMD build, make sure to also include `react` and, if you plan to\nuse the 3D component, `three` (note that `three` does not follow semantic\nversioning, last known working version is 0.126.1):\n\n```html\n\u003cscript\n  crossorigin\n  src=\"https://unpkg.com/react@16/umd/react.production.min.js\"\n\u003e\u003c/script\u003e\n\u003cscript\n  crossorigin\n  src=\"https://unpkg.com/react-dom@16/umd/react-dom.production.min.js\"\n\u003e\u003c/script\u003e\n\u003cscript\n  crossorigin\n  src=\"https://unpkg.com/three@0.126.1/build/three.min.js\"\n\u003e\u003c/script\u003e\n```\n\nSee the [`examples folder`](examples/umd/) for how to use the UMD build.\n\n## How to use\n\nThe package exports three components: the basic `\u003cVisualization /\u003e` and\n`\u003cVisualization3D /\u003e` components, and a `\u003cSelectionControls /\u003e` component that\nwraps the visualization components and handles selecting/deselecting nodes in\nthe graph.\n\nFor a 2D visualization:\n\n```js\nimport React from 'react'\nimport { Visualization } from '@acdh/network-visualization'\n\nconst MyComponent = props =\u003e (\n  \u003cdiv style={{ position: 'relative', width: '600px', height: '600px' }}\u003e\n    \u003cVisualization\n      graph={{\n        nodes: [\n          { id: 'n1', label: 'Node 1', type: 't1' },\n          { id: 'n2', label: 'Node 2', type: 't2' },\n          { id: 'n3', label: 'Node 3', type: 't2' },\n        ],\n        edges: [\n          { id: 'e1', label: 'Edge 1', source: 'n1', target: 'n2', type: 'r1' },\n          { id: 'e2', label: 'Edge 2', source: 'n1', target: 'n3', type: 'r1' },\n        ],\n        types: {\n          nodes: [\n            { id: 't1', label: 'Category 1', color: '#006699' },\n            { id: 't2', label: 'Category 2', color: '#669900' },\n          ],\n          edges: [{ id: 'r1', label: 'Relation 1', color: '#990066' }],\n        },\n      }}\n    /\u003e\n  \u003c/div\u003e\n)\n```\n\nThe `graph` prop is the only required prop. It must include the graph's nodes\nand edges, as well as a `types` object describing the node and edge types. All\nentities in the graph can have an optional `label` and a `color`, where labels\nand colors defined on individual nodes/edges take precedence over labels and\ncolors defined for node types/edge types.\n\nNote that `nodes`, `edges`, `types.nodes` and `types.edges` can be provided as\narrays, or as objects mapped by `id`, e.g.:\n\n```js\n{\n  nodes: {\n    n1: {\n      id: 'n1'\n    },\n    n2: {\n      id: 'n2',\n    },\n  },\n}\n```\n\nWhen the graph data changes during the lifetime of the component, by default new\nnodes and edges will be _added_ to the previously provided graph. If you want to\n_replace_ a graph, you can add the `replace` property to the graph object:\n\n```diff\n {\n   nodes: [],\n   edges: [],\n   types: {\n     edges: [],\n     nodes: []\n   },\n+  replace: true,\n }\n```\n\n## Selection controls\n\nClick interactions which allow selecting/deselecting nodes can be added with the\n`\u003cSelectionControls /\u003e` component:\n\n```js\nimport React from 'react'\nimport { SelectionControls as Visualization } from '@acdh/network-visualization'\n\nconst MyComponent = props =\u003e (\n  \u003cdiv style={{ position: 'relative', width: '600px', height: '600px' }}\u003e\n    \u003cVisualization dimensions={3} graph={props.graph} /\u003e\n  \u003c/div\u003e\n)\n```\n\nBy default, `SelectionControls` is an uncontrolled component, i.e. it holds the\nstate of selected nodes internally. It is possible to switch it to a controlled\ncomponent by providing a `Set` of ids with the `selectedNodeIds` prop.\n\n## Live example\n\nYou can view a live example of the components in storybook, by either locally\nrunning `npm run storybook`, or\n[here](https://acdh-network-visualization.netlify.com).\n\n## Props\n\n### Visualization and Visualization3D\n\n| prop               | type           | default          | description                                                                                                     |\n| ------------------ | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |\n| backgroundColor    | string         |                  | Canvas color                                                                                                    |\n| dagMode            | string \\| null | null             | Layout mode for directed acyclical graphs                                                                       |\n| graph              | object         |                  | Graph data, see above for the expected format                                                                   |\n| height             | number         | container height | Canvas height                                                                                                   |\n| highlightedNodeIds | Set\\\u003cstring\\\u003e  |                  | Ids of highlighted nodes                                                                                        |\n| onNodeClick        | function       |                  | Event callback fired when clicking on a node. Receives an object with `{ node, graph, forceGraph }` as argument |\n| onSimulationEnd    | function       |                  | Event callback fired when simulation ends                                                                       |\n| onSimulationTick   | function       |                  | Event callback fired every simulation tick                                                                      |\n| onZoom             | function       |                  | Event callback fired on every zoom/pan interaction                                                              |\n| selectedNodeIds    | Set\\\u003cstring\\\u003e  |                  | Ids of selected nodes                                                                                           |\n| showNeighborsOnly  | bool           | false            | Only how neighbors of selected nodes                                                                            |\n| width              | number         | container width  | Canvas width                                                                                                    |\n\n### SelectionControls\n\nHas all props from `\u003cVisualization /\u003e`, and adds:\n\n| prop           | type     | default | description                                                                                                                                                            |\n| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| dimensions     | number   | 2       | 2D or 3D layout                                                                                                                                                        |\n| onNodeDeselect | function |         | Event callback fired when node is deselected. Receives the node object as argument (and the set of currently selected node ids when used as an uncontrolled component) |\n| onNodeSelect   | function |         | Event callback fired when node is selected. Receives the node object as argument (and the set of currently selected node ids when used as an uncontrolled component)   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facdh-oeaw%2Fnetwork-visualisation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facdh-oeaw%2Fnetwork-visualisation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facdh-oeaw%2Fnetwork-visualisation/lists"}