Symbiote.js

Symbiote.js

Why does Symbiote.js exist?

Runtime Agnostic Templates (RAT) are the main reason. In Symbiote.js, a template is an HTML string that describes markup and named bindings. It is independent of a component instance, render function, runtime, and templating tool. You can define, customize, compose, render, and reuse it at any point in the application lifecycle, on the client or the server.

RAT keeps UI structure, data bindings, and actions declarative across client rendering, SSR, SSG, and hybrid rendering. Symbiote.js can also work beside other frameworks and expose UI capabilities directly to AI-agents. It requires no virtual DOM, proprietary template syntax, or mandatory build step.

All of this creates a natural symbiosis with your other technical choices.

RAT: Runtime Agnostic Templates

Documentation Code Examples npm GitHub Community

Why Symbiote.js?

Symbiote.js extends native Custom Elements with reactive data bindings, portable HTML templates, state contexts, routing, and SSR. It works directly with standard browser APIs, keeps boilerplate small, and does not require a build step.

Four design choices set it apart from most UI libraries:

1. Runtime Agnostic Templates

Many component libraries bind a template to a render function, compiler, or component instance. Symbiote.js templates remain plain HTML strings with named binding metadata. The component and its data context are resolved later, when the template is rendered or hydrated. That separation makes templates portable across runtimes and rendering strategies.

  • Write templates with standard tags and attributes, plus a compact binding syntax for reactivity.
  • Use output from the html helper, plain HTML strings, external template modules, or document-level <template> elements.
  • Let the html helper turn JavaScript binding objects into HTML binding attributes.
  • Reuse the same template on the client, on the server, or in a static generation pipeline.
  • Combine templates with any server-side template system or UI framework, including React, Vue, and Angular.
  • Replace or customize a template without moving it into component logic or restructuring the rest of the application.

2. Direct extension of the DOM

Symbiote.js uses the native DOM API instead of placing a virtual DOM, JSX compiler, or proprietary component format between your code and the browser.

  • Symbiote components are Custom Elements, so you can inspect and control them like any other DOM node.
  • Reactive state changes update bound DOM properties directly and use the browser's own optimizations.
  • Direct DOM access remains available when declarative bindings are not enough.
  • The library has zero runtime dependencies and adds little runtime weight.
  • Standard HTML, CSS, and JavaScript remain the application foundation, which avoids framework lock-in.
  • You can extend the application base class with project-specific features.

3. App-wide state without prop drilling

Symbiote.js uses the document structure as a data-flow graph. A component can connect to local state, its nearest owning ancestor, a shared group, or a named global context through the same binding syntax.

  • Reactive bindings connect template values and action handlers to local or external data contexts.
  • DOM ancestry can model data flow without prop drilling or wrapper components.
  • Shared contexts group components in the same way a name attribute groups native radio buttons.
  • Named contexts provide app-wide data sources. Namespace bindings such as APP/user give any component or template explicit access to them.
  • Components can share state while remaining loosely coupled.
  • The same state interface resolves values in browser and Node.js environments, so isomorphic components do not need separate state logic.
  • The underlying pub/sub primitives support data flows of any complexity.

4. Agentic Web and WebMCP

A handler bound to a button can also be an AI agent's tool. The optional @symbiotejs/symbiote/webmcp extension generates tools from existing click, submit, change, and input bindings when mcpToolMode is enabled. The same application logic serves people and agents.

Component tools follow the UI lifecycle: Symbiote registers them when components render and removes them when those components leave the DOM. Add toolname and tooldescription metadata to controls, or use ToolDescriptor for custom input schemas, execution logic, and state-dependent availability.

Application adapters can discover Symbiote-created tools with getActiveWebMCPTools() and invoke them with executeWebMCPTool(). Input tools insert values into controls before calling their bound handlers. Where native declarative WebMCP is supported, annotated forms keep the browser's submission and user-review behavior without duplicate Symbiote submission tools.

See the WebMCP guide for activation, data insertion, and native form support.

HTML-only applications

The optional HTML-app foundation lets you build interactive applications with HTML and JSON, without writing application JavaScript. Load its external module or import @symbiotejs/symbiote/html-app into an existing module. The core library remains independent.

  • Declare local or named state with sym-context and JSON defaults.
  • Define reusable custom elements with sym-component, their own state, and inline or referenced templates.
  • Use sym-collection for reactive record lists with editing, filtering, search, and sorting.
  • Compose views with sym-conditional, sym-router, and portable HTML chunks loaded by sym-import.
  • Save and restore data in browser storage, or configure explicit JSON requests to HTTP endpoints.

In a Markdown host that preserves trusted embedded HTML, explanations and interactive controls can share one document. Coding agents can reuse the foundation's declarative actions instead of generating event handlers and state-management code, which can reduce output token consumption.

Start with the compact Todo, explore the feature guide, or read how HTML-app compares with htmx.

More built-in features

Object bindings to child state

Bind a parent object to a child's $ property to pass several values together:

ProfilePanel.template = html`
  <profile-card ${{$: 'profile'}}></profile-card>
`;

Publishing a new profile object shallowly merges its fields into the child, registers missing keys, and preserves omitted values and the existing state proxy. Child edits do not automatically publish back to the parent. Direct assignment such as card.$ = { name: 'Alex' } uses the same merge behavior. See state merging.

Itemize API

Render dynamic lists from reactive data:

<div itemize="users">
  <template>
    <span>{{name}}</span> -- <span>{{role}}</span>
    <button ${{onclick: '^removeUser'}}>Remove</button>
  </template>
</div>
  • Update the source data and Symbiote.js updates the rendered list efficiently.
  • Each item becomes a component connected to the corresponding data context.
  • Use the item-tag attribute to render items with a dedicated component.
  • CSS transitions animate removed items without additional JavaScript.
  • Nest lists to represent structured data.
  • Enable keyed updates for efficient reordering and fewer DOM mutations.

Server-side rendering

Use the same component implementation on the server and the client. SSR.processHtml() generates complete HTML, while SSR.renderToStream() produces streamed chunks. In the browser, ssrMode attaches bindings to existing DOM without rendering it again. isoMode = true hydrates server-rendered content when present and otherwise renders the template from scratch. Hydration supports both Light DOM and Declarative Shadow DOM.

SSR: one component for server and client

Lazy rendering

Set lazyMode = true to defer a component's initialization and rendering until it enters the viewport. The lazy attribute enables the same behavior for items in an itemize container, so large lists can defer work for off-screen content. See the lazy rendering flag.

Built-in SPA router

The built-in router provides client-side navigation without another dependency:

  • Define path-based routes with :param extraction.
  • Add route guards for authentication and access control.
  • Load route components lazily.
  • Bind route data directly in templates through a named routing context.

CSS-driven animations

The animateOut helper manages exit transitions without JavaScript animation code. It sets a [leaving] attribute, waits for the CSS transitionend event, and then removes the element. The Itemize API uses the same behavior for list removals.

Security

  • Template writes support Trusted Types through a named 'symbiote' policy when the API is available.
  • Symbiote.js works with strict Content Security Policy headers.

TypeScript

Symbiote.js combines JSDoc declarations with *.d.ts files for complex and global types. JavaScript projects get static type analysis without mandatory transpilation, while TypeScript and mixed codebases can use the same source modules without extra setup.

More about RAT typing: https://github.com/symbiotejs/symbiote.js/blob/main/docs/typescript.md

Development diagnostics

Enable Symbiote.devMode for verbose warnings and import devMessages.js for full, human-readable messages. The development mode guide explains warning codes and configuration.

Ecosystem

Shadow DOM is optional, so Symbiote components can share a page with other libraries and CSS frameworks. Three.js, D3, Chart.js, and CSS utility libraries work through their usual APIs without framework adapters, wrapper components, or compatibility layers.

For teams that want a project scaffold, JSDA-Kit can create a Symbiote.js project in under a minute. It works as a static site generator for JAMstack sites or as a lightweight framework for dynamic applications. The toolkit includes SSR, esbuild bundling, automatic import maps, and a CLI that needs no configuration.

Where Symbiote.js fits

  • Rich multipart widgets and complex interactive components
  • Microfrontend architectures
  • Reusable component libraries
  • High-performance web applications
  • Framework-agnostic solutions
  • HTML-only applications with declarative state and actions
  • Meta-applications
  • JAMstack and hybrid sites
  • AI-ready applications

Try it

<script type="importmap">
  {
    "imports": {
      "@symbiotejs/symbiote": "https://esm.run/@symbiotejs/symbiote"
    }
  }
</script>

<script type="module">
  import Symbiote, { html } from '@symbiotejs/symbiote';

  export class MyComponent extends Symbiote {
    count = 0;
    onIncrement() {
      this.$.count++;
    }
  }

  // Define template:
  MyComponent.template = html`
    <h2>{{count}}</h2>
    <button ${{onclick: 'onIncrement'}}>Click me!</button>
  `;

  // Register new tag name:
  MyComponent.reg('my-component');
</script>

Use the component anywhere in your HTML:
<my-component></my-component>

Save this example as HTML and open it in a browser. It works without installation, build tools, or a local server. TypeScript, bundlers, and linters remain available when your project needs them.

For npm-based projects:

npm i @symbiotejs/symbiote

A bundler is optional and recommended for production performance.

Use with coding agents

Install the Symbiote.js skill from your project directory:

npx skills add symbiotejs/symbiote.js --skill symbiote

The skills CLI lets you choose your coding agent. Add --global to install across projects. The skill covers templates, state bindings, contexts, HTML-only applications, SSR, WebMCP, and security boundaries, with links to the detailed documentation.

Live code playground



More examples

Learn more

Documentation npm GitHub Community
26.08.2026
Agentic EAM
The future of Enterprise Asset Management
06.07.2026
JSDA-Kit 1.6.x -- What's New?
Features for Richer Static Output
03.06.2026
Symbiote.js & WebMCP
The important part of modern web usability
28.05.2026
Symbiote.js v3.7.x
What's new?
03.05.2026
Symbiote VS Lit
David and Goliath: differences, pros and cons...
11.12.2025
JSDA is very simple
A new, simple, but powerful way to build modern web applications.
28.09.2024
It was really possible?
Symbiote.js as an answer to many questions
17.09.2024
Smart HTML-tags
Simple recipe with the Artificial Intelligence
18.01.2024
Symbiote.js 2.x
Next generation of Symbiote.js is released. Let's see what's new...
RND-PRO.com © 2026 | Built with JSDA-Kit