a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1# VoltX.js
2
3[](https://codecov.io/gh/stormlightlabs/volt)
4[](https://jsr.io/@voltx/core)
5
6
7> [!WARNING]
8> VoltX.js is in active development.
9>
10> Breaking changes are expected until v1.0. Use in production at your own risk.
11
12A lightweight reactive framework for declarative UIs. Build interactive applications using only HTML attributes powered by signals.
13
14## Features
15
16- Declarative, HTML-first reactivity via `data-volt-*` attributes
17- Fine-grained signals and effects that update the DOM without a virtual DOM
18- Zero runtime dependencies and a sub-15 KB gzipped core
19- Built-in transport for SSE/WebSocket streams and JSON Patch updates
20- Hydration-friendly rendering with SSR helpers
21- Optional CSS design system and debug overlay for inspecting signal graphs
22
23## Installation
24
25### npm
26
27```bash
28npm install voltx.js
29```
30
31### JSR
32
33```bash
34npx jsr add @voltx/core
35```
36
37### Deno
38
39```typescript
40import { charge, signal } from "jsr:@voltx/core";
41```
42
43## Quick Start
44
45```html
46<div data-volt data-volt-state='{"count": 0}'>
47 <p data-volt-text="count"></p>
48 <button data-volt-on-click="count.set(count.get() + 1)">Increment</button>
49</div>
50
51<script type="module">
52 import { charge } from 'voltx.js';
53 charge();
54</script>
55```
56
57## Plugins
58
59- `data-volt-persist` – automatically sync state across reloads and tabs
60- `data-volt-url` – keep signals in sync with query params and hashes
61- `data-volt-scroll` – manage scroll restoration and anchored navigation
62- `data-volt-shift` – trigger reusable keyframe animations
63- `data-volt-surge` – apply enter/leave transitions with view-transition support
64
65Plugins are opt-in and can be combined declaratively or registered programmatically via `charge({ plugins: [...] })`.
66
67## VoltX.css
68
69VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS.
70It provides beautiful, semantic styling without requiring any CSS classes.
71Just write semantic HTML and it looks great. It's perfect for prototyping.
72
73### Features
74
75- **Typography**: Modular scale (1.25 ratio), harmonious spacing, and responsive sizing
76- **Tufte-style sidenotes**: Margin notes using `<small>` that float on desktop, inline on mobile
77- **Components**: Styled dialogs, accordions (details/summary), and pure-CSS tooltips
78- **Forms**: Consistent, accessible input styling with validation states
79- **Tables**: Zebra striping and responsive behavior
80- **Code blocks**: Syntax-appropriate styling for inline and block code
81- **Dark mode**: Automatic theme switching based on system preferences
82
83### Installation
84
85Import the CSS in your application:
86
87```typescript
88import 'voltx.js/css';
89```
90
91Or include via CDN:
92
93```html
94<link rel="stylesheet" href="https://unpkg.com/voltx.js/dist/voltx.css">
95```
96
97### Usage
98
99No classes needed. Just write semantic HTML:
100
101```html
102<article>
103 <h2>Beautiful Typography</h2>
104 <p>
105 This paragraph has proper spacing.
106 <small>This sidenote appears in the margin on wide screens.</small>
107 All elements are styled automatically.
108 </p>
109
110 <details>
111 <summary>Accordion Example</summary>
112 <p>Content revealed when opened.</p>
113 </details>
114</article>
115```
116
117See the demo app's CSS section for comprehensive examples of all features.
118
119## Documentation
120
121Full documentation available at [https://stormlightlabs.github.io/volt/](https://stormlightlabs.github.io/volt/)
122
123## Development
124
125- `pnpm install` (at the repo root) to bootstrap the workspace
126- `pnpm --filter lib dev` runs package scripts such as `build`, `test`, and `typecheck`
127- `pnpm dev` spins up the playground in `lib/dev` for interactive testing
128
129## License
130
131MIT