Widgets

Widget layouts, configuration, theming, and the DRAFT → PUBLISHED lifecycle.

A widget is a configured image layout that references an ordered list of assets. It defines how your images are displayed — the layout type, behavior settings, and visual theme.

Layout types

Vizco supports six layout types:

| Layout | Description | |---|---| | CAROUSEL | Horizontally paged images with dots and arrows | | GRID | Fixed-column grid layout | | MASONRY | Staggered grid with dynamic aspect ratios | | SLIDER | Full-width image slider with counter | | LIST_VERTICAL | Vertically scrolling image list | | LIST_HORIZONTAL | Horizontally scrolling image list |

Each layout has its own configuration options. See the Layouts guide for details.

Widget properties

NameTypeDefaultDescription
name*string—Display name
slug*string—URL-friendly identifier, unique per project. Used to fetch the widget publicly.
assetIds*UUID[]—Ordered list of asset IDs. The array order determines display order in the widget.
layout*string—One of: CAROUSEL, GRID, MASONRY, SLIDER, LIST_VERTICAL, LIST_HORIZONTAL
configJSON—Layout-specific configuration
themeJSON—Visual theme overrides
statusstring—DRAFT or PUBLISHED

Asset ordering

The assetIds array determines the display order of assets in the widget. In the dashboard widget builder, you can drag and drop asset thumbnails to reorder them. The order is preserved when saving and is reflected in the public delivery response.

Configuration

The config field contains layout-specific settings as JSON. For example, a carousel config:

Carousel config
{
"autoplay": true,
"autoplaySpeed": 3000,
"showArrows": true,
"showDots": true,
"infinite": true,
"transition": "slide",
"aspectRatio": "16/9"
}

Theming

The theme field controls visual appearance:

Theme
{
"backgroundColor": "#f9fafb",
"borderRadius": 12,
"padding": 16,
"captionColor": "#6b7280"
}

See the Theming guide for all available fields and how to override them client-side.

Lifecycle

Widgets follow a DRAFT → PUBLISHED lifecycle:

  1. DRAFT — Default state after creation. The widget can be edited freely but is not accessible via the public API.
  2. PUBLISHED — The widget is accessible via GET /api/v1/widgets/{slug} with an API key. It can still be edited.

Publishing and unpublishing

PUT/api/projects/{projectId}/widgets/{widgetId}/publishJWT
PUT/api/projects/{projectId}/widgets/{widgetId}/unpublishJWT

Unpublishing a widget immediately makes it inaccessible to all clients using the public API. Connected apps will receive an error until the widget is republished.

Fetching published widgets

Published widgets are fetched by their slug using an API key:

GET/api/v1/widgets/{widgetSlug}API Key

The response includes the widget configuration and all associated asset data, in the order specified by the widget:

Response
{
"widget": {
  "id": "...",
  "slug": "hero-carousel",
  "layout": "CAROUSEL",
  "config": "{...}",
  "theme": "{...}"
},
"assets": [
  {
    "id": "...",
    "url": "https://your-cdn.com/api/v1/deliver/...",
    "filename": "hero-1.jpg",
    "contentType": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "altText": "Hero banner"
  }
]
}
Assets & FoldersAPI Keys