Displaying Widgets

Use the VizcoWidget composable to render published widgets in your Android app.

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

Basic usage

HomeScreen.kt
import com.vizco.sdk.ui.VizcoWidget

@Composable
fun HomeScreen() {
  VizcoWidget(
      widgetSlug = "hero-carousel",
      modifier = Modifier.fillMaxWidth()
  )
}

That's it — the SDK handles fetching the widget configuration, loading images, and rendering the correct layout.

Parameters

NameTypeDefaultDescription
widgetSlug*String—The slug of the published widget to display
modifierModifierModifierStandard Compose modifier for layout and sizing
apiKeyString?nullOverride the global API key for this widget
baseUrlString?nullOverride the global base URL for this widget
themeOverridesWidgetTheme?nullClient-side theme overrides
onLoading@Composable () -> Unit—Custom loading state composable
onError@Composable (String) -> Unit—Custom error state composable

State machine

The widget goes through three states:

  1. Loading — The widget config and assets are being fetched from the API (or cache).
  2. Success — The widget is rendered with the appropriate layout.
  3. Error — Something went wrong (network error, widget not found, etc.).
sealed interface VizcoWidgetState {
  data object Loading : VizcoWidgetState
  data class Success(
      val layout: WidgetLayout,
      val configJson: String,
      val theme: WidgetTheme,
      val assets: List<ResolvedAsset>,
  ) : VizcoWidgetState
  data class Error(
      val message: String,
      val cause: Throwable? = null,
  ) : VizcoWidgetState
}

Custom loading state

VizcoWidget(
  widgetSlug = "hero-carousel",
  onLoading = {
      Box(
          modifier = Modifier.fillMaxWidth().height(200.dp),
          contentAlignment = Alignment.Center
      ) {
          CircularProgressIndicator()
      }
  }
)

Custom error state

VizcoWidget(
  widgetSlug = "hero-carousel",
  onError = { message ->
      Column(
          modifier = Modifier.fillMaxWidth().padding(16.dp),
          horizontalAlignment = Alignment.CenterHorizontally
      ) {
          Icon(Icons.Default.Warning, contentDescription = null)
          Text("Failed to load widget: $message")
      }
  }
)

Theme overrides

Override server-side theme values client-side:

import com.vizco.sdk.model.WidgetTheme

VizcoWidget(
  widgetSlug = "hero-carousel",
  themeOverrides = WidgetTheme(
      backgroundColor = "#1a1a2e",
      borderRadius = 16,
      padding = 8
  )
)

See the Theming guide for all available fields.

Next steps

  • Layouts — Explore all six layout types and their config options.
  • Theming — Customize visual appearance.
  • Caching — Understand the built-in LRU cache.
InitializationLayouts