Theming

Customize widget appearance with server-side and client-side theme overrides.

Widgets support visual theming through the theme field. Themes can be set server-side when creating the widget and overridden client-side in the Android SDK.

Theme fields

NameTypeDefaultDescription
background_colorString?nullBackground color as hex string (e.g. #f9fafb or #80f9fafb for alpha)
border_radiusInt?nullCorner radius in DP applied to the widget container
paddingInt?nullInner padding in DP
font_familyString?nullFont family name for caption text
caption_colorString?nullText color for captions as hex string

Server-side theming

Set the theme when creating or updating a widget via the API:

Widget theme
{
"theme": {
  "background_color": "#f0f4f8",
  "border_radius": 12,
  "padding": 16,
  "caption_color": "#4a5568"
}
}

The theme is stored with the widget and delivered to all clients.

Client-side overrides

Override specific theme fields in the Android SDK using themeOverrides:

ThemeOverride.kt
import com.vizco.sdk.model.WidgetTheme
import com.vizco.sdk.ui.VizcoWidget

@Composable
fun ThemedWidget() {
  VizcoWidget(
      widgetSlug = "hero-carousel",
      themeOverrides = WidgetTheme(
          backgroundColor = "#1a1a2e",
          borderRadius = 16,
          padding = 8
      )
  )
}

Client-side overrides completely replace the server-side theme. If you override backgroundColor, the server value for that field is ignored. Fields you don't set in the override remain null and the server values are used.

How theming is applied

The SDK resolves the final theme by merging server-side and client-side values:

  1. The widget's theme JSON is parsed into a WidgetTheme object.
  2. If themeOverrides is provided, non-null fields from the override replace corresponding server values.
  3. The resolved theme is passed to the layout composable.
  4. Each layout applies theme values using a themedBackground() utility that sets background color, border radius, and padding.

Color format

Colors use hex string format:

  • 6-digit: #f9fafb (RGB)
  • 8-digit: #80f9fafb (ARGB with alpha)

The SDK parses hex colors into Compose Color values at render time.

LayoutsCaching