{"id":13491114,"url":"https://github.com/vasturiano/aframe-forcegraph-component","last_synced_at":"2025-07-03T16:03:32.874Z","repository":{"id":20330205,"uuid":"89407655","full_name":"vasturiano/aframe-forcegraph-component","owner":"vasturiano","description":"Force-directed graph component for A-Frame","archived":false,"fork":false,"pushed_at":"2023-04-14T23:55:31.000Z","size":6826,"stargazers_count":76,"open_issues_count":9,"forks_count":31,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-03-15T03:55:25.888Z","etag":null,"topics":["3d","aframe","data-visualization","force-directed-graphs","threejs","vr"],"latest_commit_sha":null,"homepage":"https://vasturiano.github.io/aframe-forcegraph-component/","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/vasturiano.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-25T21:17:19.000Z","updated_at":"2024-03-04T19:39:55.000Z","dependencies_parsed_at":"2024-01-14T20:16:24.323Z","dependency_job_id":"7be37d5d-f40a-45b6-9ed0-2f404cc098e7","html_url":"https://github.com/vasturiano/aframe-forcegraph-component","commit_stats":{"total_commits":301,"total_committers":5,"mean_commits":60.2,"dds":"0.12292358803986714","last_synced_commit":"ff894dea6d5a881514a259df57b31eeb65d3956c"},"previous_names":[],"tags_count":112,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vasturiano%2Faframe-forcegraph-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vasturiano%2Faframe-forcegraph-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vasturiano%2Faframe-forcegraph-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vasturiano%2Faframe-forcegraph-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vasturiano","download_url":"https://codeload.github.com/vasturiano/aframe-forcegraph-component/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245989377,"owners_count":20705818,"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":["3d","aframe","data-visualization","force-directed-graphs","threejs","vr"],"created_at":"2024-07-31T19:00:53.661Z","updated_at":"2025-07-03T16:03:32.858Z","avatar_url":"https://github.com/vasturiano.png","language":"JavaScript","readme":"## aframe-forcegraph-component\n\n[![Version](http://img.shields.io/npm/v/aframe-forcegraph-component.svg?style=flat-square)](https://npmjs.org/package/aframe-forcegraph-component)\n[![License](http://img.shields.io/npm/l/aframe-forcegraph-component.svg?style=flat-square)](https://npmjs.org/package/aframe-forcegraph-component)\n\nA 3D Force-Directed Graph component for [A-Frame](https://aframe.io).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://vasturiano.github.io/aframe-forcegraph-component/examples/\"\u003e\n   \u003cimg width=\"80%\" src=\"https://vasturiano.github.io/aframe-forcegraph-component/examples/large-graph/preview.png\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nAn A-Frame entity component to represent a graph data structure in a VR environment using a force-directed iterative layout.\nUses [three-forcegraph](https://github.com/vasturiano/three-forcegraph) as the underlying ThreeJS component to manage the graph object.\n\nSee also the [VR](https://github.com/vasturiano/3d-force-graph-vr) and [AR](https://github.com/vasturiano/3d-force-graph-ar) standalone component versions.\n\n### API\n\n| Property             | Description                                                                                                                | Default Value |\n| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------- |\n| json-url             | URL of JSON file to load graph data directly from. Will override content of the *nodes* and *links* component properties so either use one or the other. JSON should contain an object with two list properties: *nodes* and *links*.  |               |\n| nodes                | List of node objects. *Example*: ```[{\"id\": 1, \"name\": \"first\"}, {\"id\": 2, \"name\": \"second\"}]```                           | []            |\n| links                | List of link objects. *Example*: ```[{\"source\": 1, \"target\": 2}]```                                                        | []            |\n| num-dimensions       | Number of dimensions to run the force simulation on (1, 2 or 3).                                                           | 3             |\n| dag-mode             | Apply layout constraints based on the graph directionality. Only works for [DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph) graph structures (without cycles). Choice between `td` (top-down), `bu` (bottom-up), `lr` (left-to-right), `rl` (right-to-left), `zout` (near-to-far), `zin` (far-to-near), `radialout` (outwards-radially) or `radialin` (inwards-radially). | |\n| dag-level-distance   | If `dag-mode` is engaged, this specifies the distance between the different graph depths.                                  | *auto-derived from the number of nodes* |\n| dag-node-filter      | Specify nodes to ignore during the DAG layout processing. This accessor method receives a node object and should return a `boolean` value indicating whether the node is to be included. | `node =\u003e true` |\n| on-dag-error         | Callback to invoke if a cycle is encountered while processing the data structure for a DAG layout. The loop segment of the graph is included for information, as an array of node ids. By default an exception will be thrown whenever a loop is encountered. | *throws exception* |\n| node-rel-size        | Node sphere volume per value unit.                                                                                         | 4             |\n| node-id              | Node object accessor attribute for unique node id (used in link objects source/target).                                    | id            |\n| node-val             | Node object accessor function, attribute or a numeric constant for the node numeric value (affects sphere volume).         | val           |\n| node-resolution      | Geometric resolution of each node, expressed in how many slice segments to divide the circumference. Higher values yield smoother spheres. | 8 |\n| node-visibility      | Node object accessor function, attribute or a boolean constant for whether to display the node. | true          |\n| node-color           | Node object accessor function or attribute for node color (affects sphere color).                                          | color         |\n| node-auto-color-by   | Node object accessor function (`fn(node)`) or attribute (e.g. `'type'`) to automatically group colors by. Only affects nodes without a color attribute. |               |\n| node-opacity         | Nodes sphere opacity, between [0,1].                                                                                       | 0.75          |\n| node-three-object    | Node object accessor function or attribute for generating a custom 3d object to render as graph nodes. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). If a \u003ci\u003efalsy\u003c/i\u003e value is returned, the default 3d object type will be used instead for that node.  | *default node object is a sphere, sized according to `val` and styled according to `color`.* |\n| node-three-object-extend  | Node object accessor function, attribute or a boolean value for whether to replace the default node when using a custom `nodeThreeObject` (`false`) or to extend it (`true`). | false |\n| link-source          | Link object accessor attribute referring to id of source node.                                                             | source        |\n| link-target          | Link object accessor attribute referring to id of target node.                                                             | target        |\n| link-visibility      | Link object accessor function, attribute or a boolean constant for whether to display the link line. A value of `false` maintains the link force without rendering it. | true          |                                           | desc          |\n| link-color           | Link object accessor function or attribute for line color.                                                                 | color         |\n| link-auto-color-by   | Link object accessor function (`fn(link)`) or attribute (e.g. `'type'`) to automatically group colors by. Only affects links without a color attribute. |               |\n| link-opacity         | Line opacity of links, between [0,1].                                                                                      | 0.2           |\n| link-width           | Link object accessor function, attribute or a numeric constant for the link line width. A value of zero will render a [ThreeJS Line](https://threejs.org/docs/#api/objects/Line) whose width is constant (`1px`) regardless of distance. Values are rounded to the nearest decimal for indexing purposes. | 0 |\n| link-resolution      | Geometric resolution of each link, expressed in how many radial segments to divide the cylinder. Higher values yield smoother cylinders. Applicable only to links with positive width. | 6 |\n| link-curvature       | Link object accessor function, attribute or a numeric constant for the curvature radius of the link line. Curved lines are represented as 3D bezier curves, and any numeric value is accepted. A value of `0` renders a straight line. `1` indicates a radius equal to half of the line length, causing the curve to approximate a semi-circle. For self-referencing links (`source` equal to `target`) the curve is represented as a loop around the node, with length proportional to the curvature value. Lines are curved clockwise for positive values, and counter-clockwise for negative values. Note that rendering curved lines is purely a visual effect and does not affect the behavior of the underlying forces. | 0 |\n| link-curve-rotation  | Link object accessor function, attribute or a numeric constant for the rotation along the line axis to apply to the curve. Has no effect on straight lines. At `0` rotation, the curve is oriented in the direction of the intersection with the `XY` plane. The rotation angle (in radians) will rotate the curved line clockwise around the \"start-to-end\" axis from this reference orientation. | 0 |\n| link-material        | Link object accessor function or attribute for specifying a custom material to style the graph links with. Should return an instance of [ThreeJS Material](https://threejs.org/docs/#api/materials/Material). If a \u003ci\u003efalsy\u003c/i\u003e value is returned, the default material will be used instead for that link. | *default link material is [MeshLambertMaterial](https://threejs.org/docs/#api/materials/MeshLambertMaterial) styled according to `color` and `opacity`.* |\n| link-three-object    | Link object accessor function or attribute for generating a custom 3d object to render as graph links. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). If a \u003ci\u003efalsy\u003c/i\u003e value is returned, the default 3d object type will be used instead for that link.  | *default link object is a line or cylinder, sized according to `width` and styled according to `material`.* |\n| link-three-object-extend  | Link object accessor function, attribute or a boolean value for whether to replace the default link when using a custom `linkThreeObject` (`false`) or to extend it (`true`). | false |\n| link-position-update | Getter/setter for the custom function to call for updating the position of links at every render iteration. It receives the respective link `ThreeJS Object3d`, the `start` and `end` coordinates of the link (`{x,y,z}` each), and the link's `data`. If the function returns a truthy value, the regular position update function will not run for that link. | |\n| link-directional-arrow-length     | Link object accessor function, attribute or a numeric constant for the length of the arrow head indicating the link directionality. The arrow is displayed directly over the link line, and points in the direction of `source` \u003e `target`. A value of `0` hides the arrow. | 0 |\n| link-directional-arrow-color      | Link object accessor function or attribute for the color of the arrow head. | color |\n| link-directional-arrow-rel-pos    | Link object accessor function, attribute or a numeric constant for the longitudinal position of the arrow head along the link line, expressed as a ratio between `0` and `1`, where `0` indicates immediately next to the `source` node, `1` next to the `target` node, and `0.5` right in the middle. | 0.5 |\n| link-directional-arrow-resolution | Getter/setter for the geometric resolution of the arrow head, expressed in how many slice segments to divide the cone base circumference. Higher values yield smoother arrows. | 8 |\n| link-directional-particles           | Link object accessor function, attribute or a numeric constant for the number of particles (small spheres) to display over the link line. The particles are distributed equi-spaced along the line, travel in the direction `source` \u003e `target`, and can be used to indicate link directionality. | 0 |\n| link-directional-particle-speed      | Link object accessor function, attribute or a numeric constant for the directional particles speed, expressed as the ratio of the link length to travel per frame. Values above `0.5` are discouraged. | 0.01 |\n| link-directional-particle-offset     | Link object accessor function, attribute or a numeric constant for the offset of the directional particles initial position, expressed as a value between 0 and 1, relative to a full position cycle. | 0 |\n| link-directional-particle-width      | Link object accessor function, attribute or a numeric constant for the directional particles width. Values are rounded to the nearest decimal for indexing purposes. | 0.5 |\n| link-directional-particle-color      | Link object accessor function or attribute for the directional particles color.                            | color |\n| link-directional-particle-resolution | Geometric resolution of each directional particle, expressed in how many slice segments to divide the circumference. Higher values yield smoother particles. | 4 |\n| link-directional-particle-three-object | Link object accessor function or attribute for a custom 3d object to use in the directional particles. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). Activating this will ignore the set values for the particle's width, color and resolution. | |\n| on-node-hover | Callback function for node hover events, using any [raycaster based](https://aframe.io/docs/1.2.0/components/raycaster.html) controller. The node object (or `null` if there's no node directly on the ray) is included as the first argument, and the previous node object (or `null`) as second argument. ||\n| on-link-hover | Callback function for link hover events, using any [raycaster based](https://aframe.io/docs/1.2.0/components/raycaster.html) controller. The link object (or `null` if there's no link directly on the ray) is included as the first argument, and the previous link object (or `null`) as second argument. ||\n| on-node-click | Callback function for node click events. The node object is included as sole argument. ||\n| on-link-click | Callback function for link click events. The link object is included as sole argument. ||\n| force-engine         | Which force-simulation engine to use ([*d3*](https://github.com/vasturiano/d3-force-3d) or [*ngraph*](https://github.com/anvaka/ngraph.forcelayout)).  | d3             |\n| d3-alpha-min         | [Simulation alpha min](https://github.com/vasturiano/d3-force-3d#simulation_alphaMin) parameter, only applicable if using the d3 simulation engine. | 0 |\n| d3-alpha-decay       | [Simulation intensity decay](https://github.com/vasturiano/d3-force-3d#simulation_alphaDecay) parameter, only applicable if using the d3 simulation engine. | 0.0228 |\n| d3-velocity-decay    | Nodes' [velocity decay](https://github.com/vasturiano/d3-force-3d#simulation_velocityDecay) that simulates the medium resistance, only applicable if using the d3 simulation engine. | 0.4 |\n| ngraph-physics       | Specify custom physics configuration for ngraph, according to its [configuration object](https://github.com/anvaka/ngraph.forcelayout#configuring-physics) syntax. Only applicable if using the ngraph simulation engine. | *ngraph default* |\n| warmup-ticks         | How many times to tick the force simulation engine at ignition before starting to render.                                  | 0             |\n| cooldown-ticks       | How many times to tick the force simulation engine after rendering begins before stopping and freezing the engine.         | Infinity      |\n| cooldown-time        | How long (ms) to tick the force simulation engine for after rendering begins before stopping and freezing the engine.      | 15000         |\n| on-engine-tick       | Callback function invoked at every tick of the simulation engine. ||\n| on-engine-stop       | Callback function invoked when the simulation engine stops and the layout is frozen. ||\n\nThere are also internal methods that can be invoked via the [components object](https://aframe.io/docs/0.8.0/core/component.html#accessing-a-component%E2%80%99s-members-and-methods):\n\n| Method | Arguments | Description |\n| --- | --- | --- |\n| d3Force | id: \u003ci\u003estring\u003c/i\u003e, [force: \u003ci\u003efunction\u003c/i\u003e] | Getter/setter for the internal forces that control the d3 simulation engine. Follows the same interface as `d3-force-3d`'s [simulation.force](https://github.com/vasturiano/d3-force-3d#simulation_force). Three forces are included by default: `'link'` (based on [forceLink](https://github.com/vasturiano/d3-force-3d#forceLink)), `'charge'` (based on [forceManyBody](https://github.com/vasturiano/d3-force-3d#forceManyBody)) and `'center'` (based on [forceCenter](https://github.com/vasturiano/d3-force-3d#forceCenter)). Each of these forces can be reconfigured, or new forces can be added to the system. This method is only applicable if using the d3 simulation engine. |\n| d3ReheatSimulation | - | Reheats the force simulation engine, by setting the `alpha` value to `1`. Only applicable if using the d3 simulation engine. |\n| emitParticle | link: \u003ci\u003eobject\u003c/i\u003e | An alternative mechanism for generating particles, this method emits a non-cyclical single particle within a specific link. The emitted particle shares the styling (speed, shape, color) of the regular particle props. A valid `link` object that is included in `links` should be passed as a single parameter. |\n| getGraphBbox | [nodeFilter: \u003ci\u003efunction\u003c/i\u003e] | Returns the current bounding box of the nodes in the graph, formatted as `{ x: [\u003cnum\u003e, \u003cnum\u003e], y: [\u003cnum\u003e, \u003cnum\u003e], z: [\u003cnum\u003e, \u003cnum\u003e] }`. If no nodes are found, returns `null`. Accepts an optional argument to define a custom node filter: `node =\u003e \u003cboolean\u003e`, which should return a truthy value if the node is to be included. This can be useful to calculate the bounding box of a portion of the graph. |\n| refresh | - | Redraws all the nodes/links. |\n\n### Installation\n\n```js\nimport 'aframe';\nimport 'aframe-forcegraph-component';\n```\nor using a *script* tag\n```html\n\u003cscript src=\"//cdn.jsdelivr.net/npm/aframe\"\u003e\u003c/script\u003e\n\u003cscript src=\"//cdn.jsdelivr.net/npm/aframe-forcegraph-component\"\u003e\u003c/script\u003e\n```\nthen\n```html\n\u003cbody\u003e\n  \u003ca-scene\u003e\n    \u003ca-entity forcegraph=\"json-url: myGraphData.json\"\u003e\u003c/a-entity\u003e\n  \u003c/a-scene\u003e\n\u003c/body\u003e\n```\n\n## Giving Back\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=L398E7PKP47E8\u0026currency_code=USD\u0026source=url) If this project has helped you and you'd like to contribute back, you can always [buy me a ☕](https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=L398E7PKP47E8\u0026currency_code=USD\u0026source=url)!\n","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=L398E7PKP47E8\u0026currency_code=USD\u0026source=url","https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=L398E7PKP47E8\u0026currency_code=USD\u0026source=url)!"],"categories":["Uncategorized","JavaScript"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvasturiano%2Faframe-forcegraph-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvasturiano%2Faframe-forcegraph-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvasturiano%2Faframe-forcegraph-component/lists"}