Guide · Open source
How to use A-Frame: install, build a 3D scene and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
A-Frame is an open-source web framework for building browser-based 3D, AR and VR experiences. You write HTML tags such as a-scene, a-box and a-sphere, and it runs on top of three.js and WebXR. This guide shows you how to load it, build a small scene, extend it with components and run the project locally.
A-Frameaframevr/aframe · ★ 17.7k · MIT Install options & downloads Quick start
- 1Check Node.js. Install Node.js if you plan to use npm. The README does not state a required version.
- 2Install the package. Run npm install --save aframe in your project folder.
- 3Create an HTML page. Add the aframe.min.js script to the head and an a-scene element to the body.
- 4Add entities. Place primitives such as a-box and a-sphere inside a-scene and set position, rotation and color.
- 5Open in a browser. Load the page in a WebXR-capable browser to view the scene on desktop, mobile or a headset.
- 6Add components. Attach built-in or community components to extend behaviour without writing graphics code.
What A-Frame is and who it suits
A-Frame lets you describe a 3D scene with HTML tags instead of low-level graphics code. It is a thin layer over three.js, and it handles the 3D and WebXR setup needed to run across desktop, mobile and WebXR-capable headsets.
It suits web developers adding 3D to a website, educators and artists experimenting with immersive content, and beginners comfortable with basic HTML. It is less suited to teams that need a full game engine with a visual editor, or to native apps and consoles.
Install A-Frame with npm
The simplest route is the npm package. Run the install command in your project folder. The README also shows that you can use the library from a script tag, which needs no build step.
If you bundle your code with Webpack or Vite, import the library in your JavaScript. Node.js is required for the npm install and local development steps; the README does not state an exact version.
- Install with npm: npm install --save aframe
- Or with yarn: yarn add aframe
- Import in a bundled project: import AFRAME from 'aframe';
npm install --save aframeBuild your first scene in plain HTML
Load the aframe.min.js script in the head, then place your objects inside an a-scene element in the body. Each tag is an entity, and attributes such as position, rotation and color set its properties. The example below comes from the README and draws a box, sphere, cylinder, plane and sky.
Save the file, open it in a browser and the scene renders. Coordinates are written as three numbers separated by spaces, for example position="-1 0.5 -3".
- a-box, a-sphere, a-cylinder and a-plane are primitive shapes
- a-sky sets the background color
- Use the same page on desktop, phone or a WebXR headset
<html>
<head>
<script src="https://aframe.io/releases/1.8.0/aframe.min.js"></script>
</head>
<body>
<a-scene>
<a-box position="-1 0.5 -3" rotation="0 45 0" color="#4CC3D9"></a-box>
<a-sphere position="0 1.25 -5" radius="1.25" color="#EF2D5E"></a-sphere>
<a-cylinder position="1 0.75 -3" radius="0.5" height="1.5" color="#FFC65D"></a-cylinder>
<a-plane position="0 0 -4" rotation="-90 0 0" width="4" height="4" color="#7BC8A4"></a-plane>
<a-sky color="#ECECEC"></a-sky>
</a-scene>
</body>
</html>Add behaviour with components
Components are reusable pieces of behaviour you attach to an entity. The README shows built-in attributes such as geometry, material, light and animation, and community components such as particle-system and ocean. Community components are added by loading their script before the scene.
Because A-Frame sits on the DOM, you can also reach JavaScript, DOM APIs, three.js, WebXR and WebGL directly when HTML is not enough.
- Built-in components include geometries, materials, lights, animations, models, raycasters, shadows, positional audio and tracked controllers
- Community components include particle systems, physics, multiuser, oceans and teleportation
- Press ctrl + alt + i in any scene to open the visual inspector
Run A-Frame locally for development
To work on the framework itself, clone the repository, install dependencies and start the dev server. The server runs at http://localhost:8080.
To test in VR, run the HTTPS server instead. The README says to use the On Your Network (IPv4) URL from the console with the hmd.link service on your headset, then accept the self-signed certificate warning.
- Clone the repository and install dependencies
- Start the dev server with npm start
- Run npm run start:https to test in VR
- Build distributable files with npm run dist
git clone https://github.com/aframevr/aframe.git
cd aframe && npm install
npm startWhat people use it for
- Adding an interactive 3D scene to a website
- Building a simple VR experience viewable in a headset
- Teaching 3D basics with readable HTML
- Creating immersive art pieces that run in the browser
- Extending scenes with community components such as particle systems or physics
Frequently asked questions
Is A-Frame free to use?
A-Frame is released under the MIT licence, as shown in the README. The licence badge points to the license in the repository.
How do I install A-Frame?
Run npm install --save aframe in your project, or add the aframe.min.js script tag to an HTML page. The README lists both methods.
What do I need to run A-Frame?
A WebXR-capable browser is needed for headset use, and a standard desktop or smartphone browser works without a headset. Node.js is needed for the npm and local development steps.
Why is my VR scene not showing in a headset?
The README says VR testing needs HTTPS, so run npm run start:https. Then use the hmd.link method and accept the self-signed certificate warning on the headset.
How does A-Frame compare to three.js?
A-Frame is a declarative HTML layer built on top of three.js, so you write tags rather than graphics code. The README says it is thin over three.js, so it does not replace three.js for heavy, high-fidelity work.
Where can I get help with A-Frame?
The README points to StackOverflow with the aframe tag for questions and support, and to the community page on aframe.io.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
A-Frame suits web developers, educators and beginners who want 3D or VR scenes written in HTML that run in browsers and WebXR headsets. If you need a full game engine with a visual editor, native apps or console targets, or the highest-performance 3D, look at options such as three.js, Babylon.js, PlayCanvas or React Three Fiber.
Install options & downloads