Scoped - 0.0.5

A lightweight, framework-agnostic library for building web components with reactive state, bindings, lifecycle hooks, template-based rendering and plugins.

4.1 Kb Gzipped - 12.7kb Minified

Scoped is a lightweight library designed to simplify the creation of web components.

Its main idea is to provide a minimal, framework-agnostic layer over the Custom Elements API, letting you build encapsulated, reusable UI components using a concise template syntax, reactive state, and straightforward binding mechanisms. With built-in lifecycle hooks and an extensible plugin system, Scoped empowers developers to efficiently build modern, reactive interfaces.

It encourages expressiveness and rapid prototyping, giving you fine-grained control and flexibility over your components without the overhead and complexity of traditional frameworks. Scoped lets you stay close to the platform while benefiting from reactivity, simple data flow, and composable patterns for creative and productive development.

• Installation
• Getting started
  • Component options
  • Setup function
  • Templating
  • State & Props
  • Effects
  • Computed
  • Custom events
  • Event Delegation
  • Slots
  • Lifecycle
• Plugins

Installation

npm install @petit-kit/scoped
# or
yarn add @petit-kit/scoped
# or
pnpm install @petit-kit/scoped

Getting started

import { define } from '@petit-kit/scoped';

define(
  'c-slider',
  {
    props: { value: { type: Number, default: 0 } },
  },
  ({ link, emit, actions, host }) => {
    link('value', 'value');

    actions.handleChange = (event) => {
      host.updateState({ value: event.target.valueAsNumber });
      emit('on-change', { value: event.target.valueAsNumber });
    };

    return () => `
    <div>
      <input
        type="range" min="0" max="100" step="1"
        bind:value="value"
        on:input="handleChange"
      />
      <c-number ref="number" bind:value="value"></c-number>
    </div>
  `;
  }
);

The define() function is used to declare a new component.

function define(
  tagName: string,
  options: ComponentOptions,
  setup: SetupFunction
);

It takes a tagName for naming the used tag, I recommend to prefix it with c- before.

Component options

For the ComponentOptions here the way to setup the component:

{
  props: {
    attributeName: {
      type: Number|String|Boolean,
      default: 0 // default value
    }
  },
  styles: `c-slider { color: red; }`
  plugins: [timerPlugin()], // an array of plugins
  shadow: false // activate shadow DOM
}

Setup function

The SetupFunction is run only once on mount and should return a function that return a template string.

({ host, props, state, actions, refs, link }) => {
  link('name', 'name)
  host.setState('date', new Date())

  actions.onMouseEnter = () => {
    console.log('mouseEnter')
  }

  return () => `
    <div
      ref='container'
      on:mouseEnter='onMouseEnter'
    >
      Hi ${props.name}, it's actually ${state.date}
    </div>
  `
}

host is the component itself, it got those methods:

| Method | Description | | --------------------------- | ------------------------------------------ | | host.setState(partial) | Update state + full re-render | | host.updateState(partial) | Update state, effects only (no re-render) | | host.setProps(partial) | Update props programmatically | | host.scheduleUpdate() | Schedule effects on next RAF | | host.update(fullRender) | Force update (full or partial) | | host.forceRender() | Force re-render even if template unchanged | | host.destroy() | Clean up and run destroy callbacks |

Templating

Templates in this framework are just functions that return a string of HTML. Inside your setup function, you can return a function — known as the template function — that uses template literals for HTML generation.

Basic Example

return () => `
  <div>
    <h2>Hello, ${props.name}!</h2>
    <button on:click="actions.addThing">Add thing</button>
  </div>
`;

Dynamic Content

Interpolation with ${...} gives you access to state, props, or anything in closure:

return () => `
  <ul>
    ${state.items.map((item) => `<li>${item.title}</li>`).join('')}
  </ul>
`;

Event Handlers

Use on:eventName="handler" to bind events, where handler is a function from your actions object or setup context:

({ actions }) => {
  actions.addThing = () => console.log('addThing');
  return () => `
    <button on:click="addThing">Add thing</button>
  `;
};

Arrow functions or direct expressions are not supported; you must use named action references.

Referencing DOM Elements

Use the ref attribute to assign references:

return () => `
  <input ref="inputEl" type="text">
`;

You can then access the element as refs.inputEl in your setup code or methods.

Bindings

Bindings let you connect the value of a DOM property or attribute to your component's state or props, making the element update reactively when the state changes, and optionally syncing changes back to your state.

Value Binding

For <input>, <textarea>, and <select>, use bind:value="stateKey" to bind the value to a property in your state. When the user edits the input, the component will automatically update that property.

return () => `
  <input bind:value="message">
`;

Supported Bindings

• bind:text="stateKey" - Binds textContent
• bind:html="stateKey" - Binds innerHTML
• bind:value="stateKey" — Binds the value property
• bind:checked="isChecked" — Binds the checked property of checkbox/radio
• bind:prop="key" — Generic property binding (any property, e.g. bind:min, bind:max)

Example: Checkbox

return () => `
  <input type="checkbox" bind:checked="done">
  <label>${state.done ? 'Complete' : 'Incomplete'}</label>
`;

State & props

State

State is a plain object that belongs to your component instance. It is fully reactive and any time you update the state, your component can re-render or trigger effects.

You can update state in two main ways:

• host.setState(partial): Merges the partial state and triggers a full re-render.
• host.updateState(partial): Merges the partial state and only schedules effects/computed, but does NOT re-render the template.

// Initialize state in setup (no re-render)
state.count = 0;
state.status = 'idle';

// Initialize state in setup (optional)
host.setState({ count: 0, status: 'idle' });

// Update state & trigger re-render
actions.increment = () => {
  host.setState({ count: state.count + 1 });
};

// Only update state silently without re-render
host.updateState({ status: 'busy' });

State is always available via the state object you get in your setup function:

({ state, host }) => {
  // Access current state values
  const current = state.count;
  // Set state
  host.setState({ count: current + 1 });
  // ...
};

Props

Props are values passed into your custom element as attributes or via programmatic updates. You define prop types/defaults in props on the component options.

Props are available as the props object in the setup function:

define(
  'c-my-thing',
  {
    props: {
      value: { type: Number, default: 10 },
      label: { type: String, default: 'Untitled' },
    },
  },
  ({ props }) => {
    return () => `
    <p>Value: ${props.value}</p>
    <span>${props.label}</span>
  `;
  }
);

Props are always kept up to date with attribute changes, and updating props from the outside (or via host.setProps(...)) will trigger updates in your component.

Two-way Binding:

Scoped allows props <=> state syncing using the link helper:

({ link }) => {
  link('value', 'value'); // Binds prop 'value' with state 'value'
};

This makes sure that when props.value changes from outside, your state updates, and when you change state.value, the prop and attribute reflect if configured.

Programmatic prop updates:

You can also change props from inside the component:

host.setProps({ value: 42 });

This updates the prop, reflects it as an attribute if needed, and triggers all update lifecycle hooks.

Props are also automatically parsed from their attribute string values into the appropriate type, based on your definition (Number, Boolean, etc.), so you always work with type-safe values in your setup and template logic.

Effects

Effects are functions that run in response to reactive changes and can be used for side effects, subscriptions, or manual cleanup logic within your components.

// Run on every render
effect(() => console.log('Rendered'));

// Run once (empty deps)
effect(() => {
  const sub = api.subscribe();
  return () => sub.unsubscribe();
}, []);

// Run when deps change
effect(
  (deps) => console.log('Count:', deps[0]),
  () => [state.count]
);

// Manual cleanup
const cleanup = effect(() => {
  /* ... */
});
cleanup();

Computed

Computed values are memoized values used to derive data from state or props and automatically update when their dependencies change.

const fullName = computed(
  () => `${state.firstName} ${state.lastName}`,
  () => [state.firstName, state.lastName]
);
return () => `<p>Name: ${fullName()}</p>`;

Custom events

Emit

To emit a custom event from your component, use emit(name, detail?):

actions.handleButtonClick = () => {
  host.emit('my-event', { message: 'Hello from the component!' });
};

return () => `<button on:click="handleButtonClick">Emit Event</button>`;

Listening to custom events in parent:

<my-component id="c1"></my-component>
<script>
  document.getElementById('c1').addEventListener('my-event', (e) => {
    console.log('Received:', e.detail.message);
  });
</script>

Listen

You can use listen to subscribe to events on any EventTarget (automatically cleaned up on destroy):

onMount(() => {
  // Listen to a custom event emitted by another component
  listen(
    someOtherElement, // can be `window`
    'my-event',
    (e) => {
      console.log('Got custom event with detail:', e.detail);
    }
  );
});

Event Delegation

delegate lets you efficiently handle events on descendants matching a selector:

onMount(() => {
  delegate('click', '.item', (e, target) => {
    console.log('Clicked item:', target.textContent);
    target.classList.toggle('active');
  });
});

return () => `
  <ul>
    <li class="item">Apple</li>
    <li class="item">Banana</li>
    <li class="item">Cherry</li>
  </ul>
`;

Slots

Slots allow you to render children inside your custom element, making it easy to compose interfaces or pass in dynamic content.

Basic Usage

By default, any child content placed inside your component tag will be rendered in the default slot:

<my-card>
  <h2>Title goes here</h2>
  <p>Some description or content.</p>
</my-card>

In your component template, use:

return () => `
  <div class="card">
    <slot></slot> <!-- default slot -->
  </div>
`;

Named Slots

Named slots let your users provide content for specific areas:

<my-layout>
  <div slot="sidebar">Sidebar content</div>
  <div slot="main">Main content</div>
</my-layout>

In your component:

return () => `
  <aside><slot name="sidebar"></slot></aside>
  <main><slot name="main"></slot></main>
`;

Lifecycle

Lifecycle hooks let you run code at specific moments in the component's life, such as mount, update, or destruction.

| Method | Description | | -------------------- | ------------------------ | | onMount(cb) | After mount | | onDestroy(cb) | On destroy | | onUpdate(cb) | After each update | | onBeforeUpdate(cb) | Before each update | | onFirstUpdate(cb) | Once, after first render | | onPropsChanged(cb) | When props change |

Plugins

Scoped includes a set of optional plugins to extend or enhance component behavior. You can import any of these plugins and register them via the plugins option.

Available Plugins:

• lerpPlugin & springPlugin
  Adds a reactive spring physics engine for animating values with natural, spring-like motion. Powered by @petit-kit/animate. Integrates seamlessly with the timer plugin for requestAnimationFrame-based updates.

• morphPlugin
  Provides idiomorph-based DOM morphing for efficient, non-destructive updates.

• devicePlugin
  Detects and reacts to device and input type changes (e.g., pointer type, hover support).

• lenisPlugin
  Integrates the Lenis smooth scrolling library.

• timerPlugin
  Adds easy interval, timeout, and requestAnimationFrame timers to your component logic.

• windowPlugin
  Supplies window-level utilities such as window resize and scroll event listeners.

• inViewPlugin
  Detects when an element is within the viewport and triggers handlers (uses IntersectionObserver).

• mousePlugin
  Tracks mouse position, mouse events, and allows you to listen to wheel/pointer activity.

• pointerPlugin
  Lerp mouse position

Usage Example:

import { define } from '@petit-kit/scoped';
import { inViewPlugin, timerPlugin } from '@petit-kit/scoped/plugins';

define(
  'my-component',
  {
    plugins: [inViewPlugin(), timerPlugin()],
  },
  ({ inView, timer }) => {
    // Use provided plugin APIs in your setup function
    // ...
  }
);

All plugins are tree-shakeable—import only what you need.

See each plugin's README (linked above) for API docs, options, and usage examples.