.ns-container { max-width: 900px; margin: 0 auto; padding: 20px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.6; color: #1f2937; } .ns-title { font-size: 2rem; margin-bottom: 0.5rem; color: #0f172a; } .ns-desc { font-size: 1.1rem; color: #64748b; margin-bottom: 1.5rem; } .ns-nav { display: flex; flex-wrap: wrap; gap: 8px; padding: 12px 0; border-bottom: 1px solid #e2e8f0; margin-bottom: 2rem; position: sticky; top: 0; background: white; z-index: 10; } .ns-nav-link { padding: 6px 14px; border-radius: 6px; background: #f1f5f9; color: #3b82f6; text-decoration: none; font-size: 14px; font-weight: 500; } .ns-nav-link:hover { background: #3b82f6; color: white; } .ns-section { margin-bottom: 3rem; padding-bottom: 2rem; border-bottom: 1px solid #f1f5f9; } .ns-section-title { font-size: 1.5rem; color: #1e293b; margin-bottom: 1rem; padding-top: 1rem; } .ns-section-content h3 { font-size: 1.2rem; margin-top: 1.5rem; color: #334155; } .ns-section-content p { margin: 0.5rem 0; } .ns-section-content pre { background: #1e293b; color: #e2e8f0; padding: 12px 16px; border-radius: 6px; overflow-x: auto; font-size: 13px; line-height: 1.5; } .ns-section-content code { background: #f1f5f9; padding: 2px 6px; border-radius: 3px; font-size: 0.9em; } .ns-section-content pre code { background: none; padding: 0; } .ns-section-content table { width: 100%; border-collapse: collapse; margin: 1rem 0; } .ns-section-content th, .ns-section-content td { padding: 8px 12px; border: 1px solid #e2e8f0; text-align: left; } .ns-section-content th { background: #f8fafc; font-weight: 600; } .ns-section-content img { max-width: 100%; height: auto; } .ns-back-to-top { font-size: 13px; margin-top: 1.5rem; } .ns-back-to-top a { color: #3b82f6; text-decoration: none; } .ns-footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid #e2e8f0; color: #94a3b8; font-size: 13px; text-align: center; } .ns-js-notice { background: #fef3c7; border: 1px solid #f59e0b; border-radius: 6px; padding: 12px 16px; margin-bottom: 1.5rem; font-size: 14px; color: #92400e; }

SpecifyJS

A declarative TypeScript UI framework built for performance, browser compatibility, and developer simplicity.

This page works best with JavaScript enabled. You are viewing a static version of the content.

Home

SpecifyJS

A declarative TypeScript UI framework built for performance, browser compatibility, and developer simplicity.

Zero runtime dependencies — every algorithm implemented from scratch
TypeScript-first — full type definitions, strict mode
React API parity — familiar hooks, components, and patterns
Concurrent rendering — lane-based priority system
ARIA compliant — development-time accessibility warnings

Getting Started

npm install @asymmetric-effort/specifyjs

import { createElement } from 'specifyjs';
import { createRoot } from 'specifyjs/dom';

function App() {
  return createElement('h1', null, 'Hello, SpecifyJS!');
}

createRoot(document.getElementById('root')).render(createElement(App, null));

Components

SpecifyJS includes 80+ reusable components organized into categories:

Form Components

Button, Toggle, TextField, Checkbox, RadioGroup, Select, Slider, NumberSpinner, ColorPicker, DatePicker, TimePicker, FileUpload, MultilineField, TextEditor

Data Display

Badge, Tag, DataGrid, Avatar, ListView, VirtualScroll, DigitalClock, AnalogClock

Feedback

Alert, ProgressBar, Spinner, Skeleton, EmptyState

Navigation

Tabs, Breadcrumb, Pagination, Dropdown, Menubar, Sidebar, Stepper, Toolbar, TreeNav, Accordion

Layout

Card, FlexContainer, Grid, Panel, ScrollContainer, Splitter, Footer

Overlay

Modal, Tooltip, Toast, Drawer, Popover, ContextMenu

Visualization (25+ charts)

BarGraph, LineGraph, PieGraph, Histogram, BoxPlot, BubbleChart, RadarChart, HeatMap, GanttChart, TreeMap, Sunburst, SankeyDiagram, ChordDiagram, ForceGraph, Gauge, BigNumber, WordCloud, and more.

Documentation

Complete documentation covering guides, API reference, and architecture.

Guides

3D Space Demo Guide:
Accessibility: Building accessible applications ensures that all users -- including those who rely on assistive technologies, keyboard navigation, or alternative input devices -- can interact with your UI. SpecifyJS renders standard DOM elements, so all native accessibility features of HTML and ARIA are available through `createElement`.
Async Function Evaluation:
Browser Support: SpecifyJS targets modern browsers with ES2020+ support. The framework has zero runtime dependencies, so browser compatibility is determined solely by the JavaScript and DOM APIs it uses.
Building Single-Page Applications: SpecifyJS is designed for building SPAs that compile to minified JavaScript for high-performance browser execution.
Code Splitting: Code splitting lets you break your application into smaller chunks that are loaded on demand. SpecifyJS supports this through `lazy()` for dynamic imports and `Suspense` for rendering fallback UI while chunks load.
Concurrent Rendering: Concurrent rendering allows SpecifyJS to work on multiple state updates simultaneously, prioritizing urgent interactions (like typing) over less critical updates (like filtering a large list). This keeps the UI responsive even during expensive renders.
Core Concepts: SpecifyJS elements are lightweight objects describing what to render:
Custom Hooks: Custom hooks let you extract reusable stateful logic from components. They are regular functions that call built-in hooks internally.
Deployment: This guide covers building SpecifyJS applications for production and deploying them to common hosting platforms.
Error Handling: Errors in a UI tree can leave the entire application in a broken state. SpecifyJS provides **error boundaries** -- class components that catch errors during rendering, lifecycle methods, and constructors of any component below them in the tree.
Feature Flags: SpecifyJS includes a built-in feature flag system based on the Context API. It allows you to gate UI features behind boolean flags, load flag configuration from static JSON, and toggle flags at runtime.
Forms and Validation: This guide covers building forms in SpecifyJS, from basic inputs to complex multi-step wizards with async validation.
Getting Started: - Node.js 24+
Meta Tags: The `useHead` hook lets components declaratively manage document `<head>` meta tags. Tags are applied when the component mounts and cleaned up when it unmounts, preventing stale metadata from persisting across route changes.
Migrating from React: SpecifyJS is designed with React API parity. Most React code works with minimal changes.
Performance Optimization: This guide explains how SpecifyJS renders, why unnecessary work happens, and the tools available to eliminate it.
Production Builds: Build the SpecifyJS library for distribution:
Render Safety — Render Guard System:
Routing: SpecifyJS includes a built-in hash-based router for single-page applications. The router listens to changes in the URL hash (`window.location.hash`) and renders components conditionally based on the current path. No server configuration is required -- the router works on any static file host, including GitHub Pages, S3, and Netlify.
SEO — Sitemap, Robots, LLMs, and Noscript Fallback:
State Management: SpecifyJS provides a layered approach to state management. Simple components use `useState`, components with complex transitions use `useReducer`, and cross-component state is shared through the Context API. For integration with external stores, `useSyncExternalStore` provides tear-free reads with automatic re-rendering.
Styling: SpecifyJS supports multiple approaches to styling components, from inline styles to CSS classes, CSS modules, and dynamic theming via the Context API.
Testing: SpecifyJS applications use three levels of testing.
Troubleshooting: Common questions and solutions when working with SpecifyJS.
TypeScript Patterns: SpecifyJS is a **TypeScript-first** framework. The entire codebase is written in strict mode (`"strict": true`), and all public APIs ship with full type definitions. This guide covers common typing patterns you will encounter when building SpecifyJS applications.
Wumpus World Demo: A 2D demonstration of the classic AI problem from Russell and Norvig's "Artificial Intelligence: A Modern Approach," implemented as a SpecifyJS showcase application. The demo is available at `/#/wumpus` on the showcase site.

API Reference

API Reference
Components API
Compute — GPU Compute Abstraction
DOM API
Hooks API
Math — Linear Algebra Library
Static Pre-rendering API
TypeScript Types

Concurrent Rendering

SpecifyJS implements lane-based concurrent rendering with the same priority levels as React 18:

SyncLane — highest priority, used by flushSync and discrete events
DefaultLane — normal state updates and event handlers
TransitionLane — lower priority, used with startTransition/useTransition

useTransition

Mark state updates as non-urgent so they can be interrupted by higher-priority work.

useDeferredValue

Returns a deferred copy of a value that lags behind during urgent updates.

startTransition

Standalone function for marking updates as transitions outside of components.

API Integration

SpecifyJS applications fetch data via HTTPS from API endpoints. The framework provides:

secureFetch — HTTPS-only fetch wrapper that blocks insecure requests
useFetch hook pattern — custom hook for data loading with loading/error states
Feature flags — FeatureFlagProvider for feature gating with remote JSON config