# redgin

> A lightweight (~5.3kb) library for building Web Components with surgical updates and fine-grained reactivity

Latest version **0.2.2** (published 2026-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install redgin
pnpm add redgin
yarn add redgin
bun add redgin
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2026-02-23 |
| First published | 2023-01-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 26.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | josnin |
| Maintainers | josnin |
| Keywords | web components, custom elements, reactive, lightweight, tiny, reactive web components, custom elements library, web components framework, shadow dom, vanilla js, no dependencies, reactive programming, fine-grained reactivity, surgical updates, template literals, UI library, component library, frontend, browser, javascript, typescript, reactive state, state management, reactive properties, attribute reflection, custom events, lifecycle hooks, SPA, single page application, micro frontend, framework agnostic |

## Links

- npm: https://www.npmjs.com/package/redgin
- Repository: https://github.com/josnin/redgin
- Homepage: https://github.com/josnin/redgin#readme
- Issues: https://github.com/josnin/redgin/issues
- npm.io page: https://npm.io/package/redgin

## Alternatives

- [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads
- [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads
- [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads
- [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads
- [@mesalvo/react-ui](https://npm.io/package/@mesalvo/react-ui.md) — 1.7K weekly downloads

## Recent versions

- 0.2.2 (latest) — 2026-02-23
- 0.2.1 — 2026-02-22
- 0.1.19 — 2024-01-06
- 0.1.18 — 2023-04-26
- 0.1.17 — 2023-02-12
- 0.1.16 — 2023-02-09
- 0.1.15 — 2023-02-07
- 0.1.14 — 2023-02-07
- 0.1.13 — 2023-02-07
- 0.1.12 — 2023-02-04
- 0.1.11 — 2023-01-31
- 0.1.10 — 2023-01-30
- 0.1.9 — 2023-01-24
- 0.1.8 — 2023-01-24
- 0.1.7 — 2023-01-23
- … 7 more at https://npm.io/package/redgin/versions

## README

[![NPM](https://nodei.co/npm/redgin.svg?style=flat&data=v,d&color=red)](https://nodei.co/npm/redgin/)

# RedGin

A lightweight (~5.3kb) library that solves the pain points of native Web Components. RedGin offers fine-grained reactivity, surgical updates, and intuitive APIs - making Web Components actually enjoyable to build.

## Why RedGin?

Native Web Components are powerful but come with friction:

| Pain Point | Native Web Components | RedGin |
|------------|----------------------|--------|
| **Boilerplate** | Manual lifecycle callbacks, attributeChangedCallback, getters/setters | Zero boilerplate with `getset` and `propReflect` |
| **Reactivity** | Manual observation with `attributeChangedCallback` | Automatic reactivity with `watch`, `s()`, and fine-grained updates |
| **Template Updates** | Manual DOM manipulation | Surgical updates - only changed parts re-render |
| **Attribute Reflection** | Manual sync between properties and attributes | Automatic with `propReflect` |
| **Event Binding** | `addEventListener` boilerplate | Inline events with `on()` |
| **Style Sharing** | Duplicated styles per component | Global `shareStyle` injection |
| **Performance** | Full re-renders on any change | Only changed elements update |
| **TypeScript** | Complex typing for custom elements | First-class TypeScript support |

## Core Philosophy

RedGin is built around **surgical updates** - only the elements that need to change, change. No virtual DOM, no heavy diffing, just precise, targeted updates to your components.

## Key Features

- **🎯 Surgical Rendering**: Update only what changes - perfect for large lists
- **📝 Template Literals**: Write components using familiar JS template syntax
- **⚡️ Fine-grained Reactivity**: Multiple reactivity patterns (`watch`, `s()`, `getset`, `propReflect`)
- **🔗 Attribute Binding**: Smart `attr()` helper for dynamic attributes
- **🔄 Property Reflection**: Sync properties with attributes using `propReflect`
- **📊 Reactive Getters/Setters**: Create reactive state with `getset`
- **🎨 Style Management**: Global style injection with `shareStyle` and scoped styles with `css`
- **📘 TypeScript Ready**: Full type safety and IntelliSense

## Installation

### Via npm
```bash
npm i redgin
```

## Via CDN

```js
<script type="module" src="https://cdn.jsdelivr.net/npm/redgin@latest/dist/redgin.min.js"></script>
```


## Quick Start

```js
import { RedGin, getset, on, html } from 'redgin';

class Counter extends RedGin {
  count = getset(0);

  render() {
    return html`
      <button ${on('click', () => this.count++)}>
        Count: ${this.count}
      </button>
    `;
  }
}

customElements.define('my-counter', Counter);
```

## API Reference


### Core Helpers

| Helper | Purpose | Example |
| :--- | :--- | :--- |
| `getset(initial)` | Creates reactive property with getter/setter | `count = getset(0)` |
| `propReflect(initial)` | Reactive property that reflects to attribute | `theme = propReflect('light')` |
| `watch(deps, callback)` | Fine-grained control - rerenders when specified dependencies change | `${watch(['count', 'theme'], () => html`<div>...</div>`)}` |
| `s(callback)` | Shorthand for reactive value binding | `${s(() => this.count)}` |
| `attr(name, callback)` | Surgical attribute binding | `${attr('disabled', () => !this.editable)}` |
| `on(event, handler)` | Event listener binding | `${on('click', () => this.save())}` |
| `html` | Template literal tag for HTML | `html`<div>Hello</div>`` |

### Style Helpers

| Helper | Purpose | Example |
| :--- | :--- | :--- |
| `css` | Template literal tag for component-scoped styles | `styles = [css`.card { padding: 1rem; }`]` |
| `shareStyle(styles)` | Injects global styles across all components | `shareStyle(css:host { --brand: blue; })` |


## Lifecycle Methods

* onInit() - After first render
* onDoUpdate() - After data sync
* onUpdated() - After every attribute change/requestUpdate

## Style Management Examples

### Global Design System with shareStyle
import { RedGin, shareStyle, css, html } from 'redgin';

// Share Bootstrap globally (injected once, used everywhere)
shareStyle('<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">')

// Share design tokens across all components
```js
shareStyle(css`
  :host {
    --brand-primary: #007bff;
    --brand-success: #28a745;
    --card-shadow: 0 4px 6px rgba(0,0,0,0.1);
  }
  
  .rg-card {
    border-radius: 8px;
    box-shadow: var(--card-shadow);
    transition: transform 0.2s;
  }
`);

class ProductCard extends RedGin {
  // Component-specific styles (merged with shared styles)
  styles = [css`
    .local-price { color: var(--brand-success); font-weight: bold; }
  `]

  render() {
    // Bootstrap classes work without local import!
    return html`
      <div class="rg-card p-3">
        <div class="local-price">$120.00</div>
        <button class="btn btn-primary">Buy Now</button>
      </div>
    `;
  }
}
```

## Reactivity Patterns: watch vs s()

### RedGin offers two complementary reactivity patterns:

## s() - Smart Auto-detection
```js
// Automatically tracks dependencies
render() {
  return html`
    <div>${s(() => this.count)}</div>
    <div>${s(() => this.theme)}</div>
  `;
}
```

## watch - Explicit Control
```js
// Fine-grained control over dependencies
render() {
  return html`
    ${watch(['count', 'theme'], () => html`
      <div class="${this.theme}">
        Count: ${this.count}
      </div>
    `)}
  `;
}
```


## Examples

Check out these live examples demonstrating RedGin's capabilities:

### Basic Examples
* [Simple Counter](https://github.com/josnin/redgin/tree/Dev/samples) - Getting started with RedGin
* [Two-way Data Binding](https://github.com/josnin/redgin/tree/Dev/samples) - Using getset and events
* [Todo App](https://github.com/josnin/redgin/tree/Dev/samples) - Classic todo example


### Style Examples

* [Bootstrap Integration](https://github.com/josnin/redgin/tree/Dev/samples) - Using shareStyle with CSS frameworks
* [Design Tokens](https://github.com/josnin/redgin/tree/Dev/samples) - Global theme variables
* [Scoped Styles](https://github.com/josnin/redgin/tree/Dev/samples) - Component-specific CSS


### Advanced Patterns
* [Surgical List Updates (1,000+ items)](https://github.com/josnin/redgin/tree/Dev/samples) - Only updated rows re-render
* [E-commerce Application](https://github.com/josnin/redgin/tree/Dev/samples) - Cart, checkout, and async operations
* [CRM Dashboard](https://github.com/josnin/redgin/tree/Dev/samples) - Multi-view with modals and pipeline
* [Parent-Child Communication](https://github.com/josnin/redgin/tree/Dev/samples) - Custom events and props

### Integration Examples

* [TypeScript Support](https://github.com/josnin/redgin/tree/Dev/samples) - Full type safety
* [With Bootstrap](https://github.com/josnin/redgin/tree/Dev/samples) - Using CSS frameworks
* [Property Reflection](https://github.com/josnin/redgin/tree/Dev/samples) - Syncing props with attributes

## Performance

* Surgical Updates: Only changed elements re-render
* Bundle Size: ~5.3kb minified + gzipped
* Memory: Zero virtual DOM overhead
* Style Injection: Global styles shared once, not duplicated per component

## Contributing

We welcome contributions!
```
git clone https://github.com/josnin/redgin.git
cd redgin
npm install
npm run dev
```

## Reference
https://web.dev/custom-elements-best-practices/

https://web.dev/shadowdom-v1/


## Help

Need help? Open an issue in: [ISSUES](https://github.com/josnin/redgin/issues)


## Contributing
Want to improve and add feature? Fork the repo, add your changes and send a pull request.

---
_Source: https://npm.io/package/redgin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._