Skip to content

Widget Utils is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.

Notifications You must be signed in to change notification settings

Stackla/widget-utils

Repository files navigation

@stackla/widget-utils

🎨 A comprehensive TypeScript utility library for building powerful User-Generated Content (UGC) widgets

npm version

πŸš€ Overview

@stackla/widget-utils is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.

✨ Features

  • 🎯 TypeScript First - Fully typed API for excellent IDE support and type safety
  • 🎨 Flexible Templating - Support for Handlebars templates with custom helpers
  • βš›οΈ JSX Support - Build widgets using JSX syntax without React
  • πŸŽͺ Widget Loading - Automated widget initialization and lifecycle management
  • πŸ”„ Infinite Scrolling - Built-in hooks for seamless content loading
  • πŸ“¦ Modular Architecture - Import only what you need with tree-shakeable exports
  • 🎠 Extension Support - Includes Swiper carousel integration out of the box
  • 🎨 CSS Variables - Dynamic theming and styling support
  • πŸ“‘ Event System - Comprehensive event handling for widget interactions
  • πŸ”Œ Embed Utilities - Easy widget embedding for both v2 and v3 widgets

πŸ“¦ Installation

npm install @stackla/widget-utils
yarn add @stackla/widget-utils
pnpm add @stackla/widget-utils

🎯 Quick Start

Basic Widget Setup

import { loadWidget } from "@stackla/widget-utils"

// Initialize a widget with default settings
const sdk = await loadWidget({
  features: {
    showTitle: true,
    preloadImages: true,
    addNewTilesAutomatically: true
  }
})

Using JSX for Widget Components

import { jsx } from '@stackla/widget-utils/jsx';

const TileComponent = ({ title, image }) => (
  <div className="tile">
    <img src={image} alt={title} />
    <h3>{title}</h3>
  </div>
);

πŸ“š Module Reference

Core Modules

@stackla/widget-utils (Main Export)

The primary entry point providing widget loading, core types, events, and library utilities.

Key Exports:

  • loadWidget() - Initialize and configure widgets
  • ISdk - TypeScript interface for widget SDK
  • Widget lifecycle hooks and event handlers

@stackla/widget-utils/types

Comprehensive TypeScript type definitions for widgets, tiles, components, and services.

Includes:

  • Widget, Tile, Placement - Core data types
  • WidgetOptions, WidgetSettings - Configuration types
  • Service interfaces for tiles, events, and widgets
  • Component types for static content, products, and UGC

@stackla/widget-utils/jsx

JSX-to-HTML runtime that lets you write components using JSX syntax without React.

Features:

  • Lightweight JSX transformation
  • Event handler support
  • Ref support for DOM access
  • Type-safe JSX elements

@stackla/widget-utils/handlebars

Handlebars template engine with custom helpers designed for widget rendering.

Custom Helpers:

  • {{tile}} - Render tile components
  • {{ifEquals}} - Conditional rendering
  • {{lazy}} - Lazy loading support
  • {{join}} - Array joining
  • {{ifAutoPlayVideo}} - Video autoplay detection
  • {{ifHasProductTags}} - Product tag checking
  • {{ifHasPublicTags}} - Public tag checking
  • {{tagFallbackUsername}} - Username fallback logic

@stackla/widget-utils/libs

Core library utilities for widget features and functionality.

Includes:

  • CSS variable management
  • Widget feature toggles
  • Layout utilities
  • Tile manipulation helpers

@stackla/widget-utils/components

Pre-built component utilities for common widget patterns.

Available Components:

  • Static content components
  • Product display components
  • Share menu components
  • Add-to-cart components
  • UGC tile components

@stackla/widget-utils/extensions

Widget extensions for enhanced functionality.

Current Extensions:

  • Swiper - Carousel/slider integration

@stackla/widget-utils/extensions/swiper

Full Swiper carousel integration for creating image/content sliders.

Features:

  • Automatic initialization
  • Responsive configuration
  • Touch/swipe support
  • Navigation and pagination

@stackla/widget-utils/events

Event system for widget lifecycle and user interactions.

Event Types:

  • Widget initialization events
  • Tile interaction events
  • Load more events
  • User action events

@stackla/widget-utils/embed

Utilities for embedding widgets into web pages.

Features:

  • Support for v2 and v3 widgets
  • Environment configuration (staging/production)
  • Auto-detection of widget version
  • Shadow DOM support

@stackla/widget-utils/templates

Template utilities and pre-built templates.

@stackla/widget-utils/bundle

Bundled distribution for direct browser usage.

πŸ”§ Configuration

Widget Settings

interface WidgetSettings {
  features?: {
    showTitle?: boolean // Display widget title
    preloadImages?: boolean // Preload images for performance
    disableWidgetIfNotEnabled?: boolean // Auto-disable on config
    addNewTilesAutomatically?: boolean // Auto-add new tiles
    handleLoadMore?: boolean // Enable load more functionality
    hideBrokenImages?: boolean // Hide broken image tiles
    loadTileContent?: boolean // Load tile content dynamically
    loadTimephrase?: boolean // Load time phrases
  }
  callbacks?: {
    // Custom callback functions
  }
  templates?: {
    // Custom templates
  }
  config?: {
    // Additional configuration
  }
}

🎨 Examples

Creating a Gallery Widget

import { loadWidget } from "@stackla/widget-utils"
import { renderTilesWithTemplate } from "@stackla/widget-utils/handlebars"

const sdk = await loadWidget({
  features: {
    preloadImages: true,
    hideBrokenImages: true
  }
})

const tiles = await sdk.getTiles()
const html = await renderTilesWithTemplate(tileTemplate, tiles, {
  wid: "your-widget-id"
})

Using Swiper Extension

import { initSwiper } from "@stackla/widget-utils/extensions/swiper"

const swiper = initSwiper(".swiper-container", {
  slidesPerView: 3,
  spaceBetween: 30,
  navigation: true,
  pagination: {
    clickable: true
  }
})

Embedding a Widget

import { embed } from "@stackla/widget-utils/embed"

await embed({
  widgetId: "your-widget-id",
  root: document.getElementById("widget-container"),
  environment: "production",
  dataProperties: {
    // Custom data attributes
  }
})

πŸ—οΈ Project Structure

src/
β”œβ”€β”€ constants.ts           # Global constants
β”œβ”€β”€ embed/                 # Widget embedding utilities
β”œβ”€β”€ events/                # Event system
β”œβ”€β”€ fonts.ts              # Font loading utilities
β”œβ”€β”€ handlebars/           # Handlebars templates and helpers
β”œβ”€β”€ hooks/                # React hooks
β”œβ”€β”€ index.ts              # Main entry point
β”œβ”€β”€ libs/                 # Core library utilities
β”‚   β”œβ”€β”€ components/       # Component utilities
β”‚   β”œβ”€β”€ css-variables.ts  # CSS variable management
β”‚   β”œβ”€β”€ extensions/       # Widget extensions
β”‚   β”œβ”€β”€ jsx-html.ts       # JSX runtime
β”‚   β”œβ”€β”€ tile.lib.ts       # Tile utilities
β”‚   β”œβ”€β”€ widget.features.ts # Widget features
β”‚   β”œβ”€β”€ widget.layout.ts   # Layout utilities
β”‚   └── widget.utils.ts    # Widget utilities
β”œβ”€β”€ styles/               # Style utilities
β”œβ”€β”€ types/                # TypeScript type definitions
β”‚   β”œβ”€β”€ components/       # Component types
β”‚   β”œβ”€β”€ core/            # Core types
β”‚   β”œβ”€β”€ services/        # Service types
β”‚   └── loader.ts        # Loader types
└── widget-loader.ts      # Widget loader implementation

πŸ§ͺ Development

Running Tests

npm test

Building

npm run build

Linting

npm run lint

Type Checking

npm run typecheck

πŸ“ Contributing

Contributions are welcome! Please ensure your code:

  • Passes all tests (npm test)
  • Follows the linting rules (npm run lint)
  • Includes proper TypeScript types
  • Is documented with JSDoc comments where appropriate

πŸ”— Links

🎯 Use Cases

  • Social Media Galleries - Display Instagram, Twitter, and other social feeds
  • Product Showcases - Feature user-generated product reviews and photos
  • Event Coverage - Aggregate and display event content from multiple sources
  • Community Walls - Create interactive community content displays
  • Marketing Campaigns - Build engaging campaign landing pages with UGC

Built with ❀️ by Nosto

About

Widget Utils is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors 8