Displaying Widgets

Use the VizcoWidget component to render published widgets in your React app.

The VizcoWidget component fetches a published widget by its slug and renders it using the appropriate layout.

Basic usage

HeroSection.tsx
import { VizcoWidget } from "@vizco/react";

export function HeroSection() {
return <VizcoWidget slug="hero-carousel" />;
}

The component handles fetching, caching, loading states, and rendering the correct layout automatically.

Props

NameTypeDefaultDescription
slug*string—The slug of the published widget to display
onAssetClick(asset: ResolvedAsset) => void—Callback when a user clicks an asset
onLoading() => ReactNode—Custom loading state renderer
onError(message: string) => ReactNode—Custom error state renderer
themeOverridesPartial<WidgetTheme>—Override theme properties from the server configuration
classNamestring—CSS class name for the outer container

Handling asset clicks

<VizcoWidget
slug="product-gallery"
onAssetClick={(asset) => {
  console.log("Clicked:", asset.filename);
}}
/>

Custom loading and error states

<VizcoWidget
slug="hero-carousel"
onLoading={() => <div className="skeleton h-64 w-full" />}
onError={(msg) => <div className="text-red-500">Error: {msg}</div>}
/>

Theme overrides

Override server-defined theme properties locally:

<VizcoWidget
slug="hero-carousel"
themeOverrides={{
  backgroundColor: "#000000",
  borderRadius: 16,
  padding: 8,
}}
/>

Supported layouts

All six layout types are supported:

| Layout | Component | |---|---| | CAROUSEL | Carousel with autoplay, dots, and arrow navigation | | GRID | Fixed-column grid | | MASONRY | Staggered grid with dynamic heights | | SLIDER | Full-width slider with counter | | LIST_VERTICAL | Vertically scrolling list with optional captions | | LIST_HORIZONTAL | Horizontally scrolling list with snap |

Caching

Widget data is cached in memory for the lifetime of the page. Subsequent renders of the same slug will use the cached data without additional network requests.

InitializationOverview