SamsaraJS is a library for building continuous user interfaces with hardware-accelerated 3D transforms, physics-based transitions, and gesture support. This walkthrough demonstrates how to start a new project using Samsara, including installation, minimal setup, and example code for both vanilla JavaScript and React integration.
Installation#
You can install Samsara in several ways. The most common is via npm:
npm install samsarajs
Samsara requires a small CSS file for proper functionality. After installation, ensure you include dist/samsara.css in your project. For example, in your HTML:
<link rel="stylesheet" href="node_modules/samsarajs/dist/samsara.css">
Alternatively, you can clone the repository and use the files directly, or include the prebuilt bundle via a script tag for quick demos. See the official README for details.
Minimal "Hello World" Example#
Below is a minimal example using Samsara with CommonJS (Node-style) modules. This example creates a blue square surface, centers it, and mounts it to the DOM.
// Import Samsara modules
var Samsara = require('samsarajs');
var Surface = Samsara.DOM.Surface;
var Context = Samsara.DOM.Context;
var Transform = Samsara.Core.Transform;
// Create a surface
var surface = new Surface({
content: 'Hello, Samsara!',
size: [200, 200],
origin: [.5, .5],
properties: { background: 'blue', color: 'white', textAlign: 'center', lineHeight: '200px' },
classes: ['hello-samsara']
});
// Create a context (root of the render tree)
var context = new Context();
// Add the surface to the context, center it, and apply a rotation
context
.add({
transform: Transform.rotateZ(Math.PI / 8),
align: [.5, .5]
})
.add(surface);
// Mount the context to a DOM element
context.mount(document.getElementById('root'));
In your HTML, ensure you have a container element:
<div id="root"></div>
Using Samsara with ES6 Modules#
You can also use Samsara with ES6 imports:
import * as Samsara from 'samsarajs';
const Surface = Samsara.DOM.Surface;
const Context = Samsara.DOM.Context;
const surface = new Surface({ content: 'Hello, ES6!', size: [200, 200] });
const context = new Context();
context.add(surface);
context.mount(document.getElementById('root'));
Integrating Samsara with React#
Samsara can be integrated with React by rendering React components into a Samsara Surface's DOM element. For example:
import * as Samsara from 'samsarajs';
import React from 'react';
import ReactDOM from 'react-dom';
const Surface = Samsara.DOM.Surface;
const Context = Samsara.DOM.Context;
// Create a Samsara surface with a unique class
const surface = new Surface({
size: [300, 100],
classes: ['react-samsara-surface']
});
const context = new Context();
context.add(surface);
context.mount(document.getElementById('root'));
// Render a React component into the Samsara surface
ReactDOM.render(
<div style={{ color: 'red', fontSize: 24 }}>Hello from React!</div>,
document.querySelector('.react-samsara-surface')
);
Project Scaffolding#
For a more automated setup, you can use the Yeoman generator for Samsara, which scaffolds a project structure for you. See the generator-samsara documentation for installation and usage instructions.
Notes#
- Samsara does not enforce a specific project structure or require configuration files beyond including the CSS and mounting the context to a DOM element.
- Examples and demos can be found in the
examplesdirectory of the Samsara repository.
For more details and advanced usage, refer to the official Samsara README and the examples.