Skip to Content
V0.2Getting Started

Getting Started

An earlier release

These pages document @evanion/react-widget 0.2.0. npm install @evanion/react-widget gives you 0.3.3, documented here. Values on this page were produced by running 0.2.0 in CI at d50a1c6 and are not re-executed.

Learn how to build dynamic, composable user interfaces with the React Widget System.

Installation

Install the package using your preferred package manager:

npm install @evanion/react-widget
yarn add @evanion/react-widget
pnpm add @evanion/react-widget

Core Concepts

The React Widget System is built around three main concepts:

  1. Widget Components - React components that define how widgets look and behave
  2. Widget Configuration - Data that describes which widgets to render and with what props
  3. Widget System - The engine that renders widgets from configuration

Basic Example

Let’s create a simple blog sidebar with news and user information:

import { createWidgets } from '@evanion/react-widget';
 
// 1. Define your widget components
const NewsTeaser = ({ title, publishedAt, body }) => (
  <article className="news-teaser">
    <h3>{title}</h3>
    <time>{publishedAt.toLocaleDateString()}</time>
    <p>{body}</p>
  </article>
);
 
const UserSidebar = ({ username, avatar, messages }) => (
  <div className="user-info">
    <img src={avatar} alt={username} />
    <span>{username}</span>
    <span>{messages} messages</span>
  </div>
);
 
// 2. Create the widget system
const { Widgets } = createWidgets({
  components: {
    news: NewsTeaser,
    userInfo: UserSidebar,
  },
});
 
// 3. Define your layout data
const sidebarItems = [
  {
    id: 'userinfo',
    type: 'userInfo',
    props: {
      username: 'Evanion',
      avatar: 'https://evanion.com/avatar.jpg',
      messages: 5,
    },
  },
  {
    id: 'news1',
    type: 'news',
    props: {
      title: 'Breaking News',
      publishedAt: new Date('2024-01-15'),
      body: 'This is a sample news article...',
    },
  },
];
 
// 4. Render your widgets
function BlogSidebar() {
  return <Widgets items={sidebarItems} />;
}

Live Demo

Try editing the code below to see how the widget system works:

The interactive example this release showed here runs against the current source, so it is on the same page under /next/ and not on this one.

Widget Data Structure

Each widget item follows this structure:

interface WidgetItem {
  id: string; // Unique identifier
  type: string; // Widget type (must match a component key)
  props: object; // Props to pass to the widget component
  children?: WidgetItem[]; // Optional nested widgets
}

TypeScript Support

The library provides full TypeScript support with generic types:

import { createWidgets, WidgetProps } from '@evanion/react-widget';
 
// Define your widget types
type MyWidgets = {
  news: WidgetProps<'news', { title: string; publishedAt: Date; body: string }>;
  userInfo: WidgetProps<
    'userInfo',
    { username: string; avatar: string; messages: number }
  >;
};
 
// Create typed widget system
const { Widgets } = createWidgets<MyWidgets>({
  components: {
    news: NewsTeaser,
    userInfo: UserSidebar,
  },
});

Next Steps

Need Help?

Last updated on
ExamplesPlayground