π¨ A comprehensive TypeScript utility library for building powerful User-Generated Content (UGC) widgets
@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.
- π― 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
npm install @stackla/widget-utilsyarn add @stackla/widget-utilspnpm add @stackla/widget-utilsimport { loadWidget } from "@stackla/widget-utils"
// Initialize a widget with default settings
const sdk = await loadWidget({
  features: {
    showTitle: true,
    preloadImages: true,
    addNewTilesAutomatically: true
  }
})import { jsx } from '@stackla/widget-utils/jsx';
const TileComponent = ({ title, image }) => (
  <div className="tile">
    <img src={image} alt={title} />
    <h3>{title}</h3>
  </div>
);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
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
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
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
Core library utilities for widget features and functionality.
Includes:
- CSS variable management
- Widget feature toggles
- Layout utilities
- Tile manipulation helpers
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
Widget extensions for enhanced functionality.
Current Extensions:
- Swiper - Carousel/slider integration
Full Swiper carousel integration for creating image/content sliders.
Features:
- Automatic initialization
- Responsive configuration
- Touch/swipe support
- Navigation and pagination
Event system for widget lifecycle and user interactions.
Event Types:
- Widget initialization events
- Tile interaction events
- Load more events
- User action events
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
Template utilities and pre-built templates.
Bundled distribution for direct browser usage.
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
  }
}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"
})import { initSwiper } from "@stackla/widget-utils/extensions/swiper"
const swiper = initSwiper(".swiper-container", {
  slidesPerView: 3,
  spaceBetween: 30,
  navigation: true,
  pagination: {
    clickable: true
  }
})import { embed } from "@stackla/widget-utils/embed"
await embed({
  widgetId: "your-widget-id",
  root: document.getElementById("widget-container"),
  environment: "production",
  dataProperties: {
    // Custom data attributes
  }
})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
npm testnpm run buildnpm run lintnpm run typecheckContributions 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
- 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