Blocks

Blocks are the building blocks of screens. Each screen contains an ordered array of blocks rendered top-to-bottom. Interactive blocks (Choice, Text Input, Slider) record user answers under their key property — you receive these in FlwKitCompletionResult.answers when the flow completes.

Displays a title with an optional subtitle. Typically the first block on a screen.

Property	Type	Default	Description
`type`	`"header"`	—	Block type.
`title`	`string`	—	Primary headline text.
`subtitle`	`string`	—	Secondary text below the title.
`align`	`"left" \| "center" \| "right"`	`"left"`	Title alignment.
`color`	`string`	theme `textPrimary`	Hex color for the title.
`opacity`	`number`	`100`	Title opacity, 0–100.
`fontWeight`	`"normal" \| "bold"`	`"bold"`	Title font weight.
`fontStyle`	`"normal" \| "italic"`	`"normal"`	Title font style.
`fontSize`	`number`	`24`	Title font size in pixels.
`spacing`	`number`	—	Letter spacing in pixels.
`subtitleColor`	`string`	theme `textSecondary`	Hex color for the subtitle.
`subtitleOpacity`	`number`	`100`	Subtitle opacity, 0–100.
`subtitleFontSize`	`number`	`16`	Subtitle font size in pixels.
`subtitleAlign`	`"left" \| "center" \| "right"`	inherits `align`	Subtitle alignment.
`subtitleSpacing`	`number`	`0`	Subtitle letter spacing in pixels.

{
  "type": "header",
  "title": "Welcome to the app",
  "subtitle": "Let's get you set up in 2 minutes.",
  "align": "center",
  "fontSize": 28
}

Description

A block of body text. Use it for explanatory copy between other blocks.

Property	Type	Default	Description
`type`	`"description"`	—	Block type.
`text`	`string`	—	Body text to display.
`align`	`"left" \| "center" \| "right"`	`"left"`	Text alignment.
`color`	`string`	theme `textSecondary`	Hex color.
`opacity`	`number`	`100`	Opacity, 0–100.
`fontWeight`	`"normal" \| "bold"`	`"normal"`	Font weight.
`fontStyle`	`"normal" \| "italic"`	`"normal"`	Font style.
`fontSize`	`number`	`16`	Font size in pixels.
`spacing`	`number`	`0`	Letter spacing in pixels.

{
  "type": "description",
  "text": "FlwKit lets you update onboarding flows without shipping a new app version.",
  "align": "center"
}

Media

Displays an image or video asset. The backend resolves asset IDs to public URLs before serving the flow.

Property	Type	Default	Description
`type`	`"media"`	—	Block type.
`url`	`string`	—	Resolved public URL of the asset. Set by the backend.
`video_url`	`string`	—	URL of a video asset.
`aspect`	`"square" \| "wide" \| "tall"`	—	Aspect ratio preset.
`align`	`"left" \| "center" \| "right"`	`"center"`	Horizontal alignment.
`width`	`number \| "auto" \| string`	`"auto"`	Width in pixels, `"auto"`, or a percentage like `"100%"`.
`height`	`number`	—	Height in pixels.
`borderRadius`	`number`	—	Corner radius in pixels.
`padding`	`{ vertical, horizontal }`	—	Internal padding in pixels.
`margin`	`{ top, bottom, left, right }`	—	External margin in pixels.

{
  "type": "media",
  "url": "https://assets.flwkit.com/your-image.png",
  "aspect": "wide",
  "borderRadius": 12
}

Choice

A list of selectable options. Supports single-select and multi-select. Records the selected label(s) under the block's key.

Property	Type	Default	Description
`type`	`"choice"`	—	Block type.
`key`	`string`	—	Required. Answer key in `FlwKitCompletionResult.answers`.
`options`	`ChoiceOption[]`	—	Required. List of options to display.
`multiple`	`boolean`	`false`	Allow selecting more than one option.
`backgroundColor`	`string`	—	Unselected option background (hex).
`activeBackgroundColor`	`string`	—	Selected option background (hex).
`borderColor`	`string`	—	Option border color (hex).
`borderWidth`	`number`	—	Border width in pixels.
`borderRadius`	`number`	—	Corner radius in pixels.
`height`	`number`	—	Option row height in pixels.
`color`	`string`	theme `textPrimary`	Option label text color (hex).

ChoiceOption

Property	Type	Description
`label`	`string`	Display text shown to the user.
`value`	`string`	Internal value (mapped to label in completion result).
`emoji`	`string`	Emoji shown alongside the label.
`action`	`"next" \| "back" \| "skip" \| "close" \| "submit"`	Per-option navigation action on selection.

answers["goal"] in FlwKitCompletionResult contains the option label (e.g. "Lose weight"), not the raw value ("lose_weight").

{
  "type": "choice",
  "key": "goal",
  "options": [
    { "label": "Lose weight", "value": "lose_weight", "emoji": "🏃" },
    { "label": "Build muscle", "value": "build_muscle", "emoji": "💪" },
    { "label": "Improve flexibility", "value": "flexibility", "emoji": "🧘" }
  ]
}

Text Input

A single-line text field. Records entered text under the block's key.

Property	Type	Default	Description
`type`	`"text_input"`	—	Block type.
`key`	`string`	—	Required. Answer key.
`placeholder`	`string`	—	Placeholder text.
`input_type`	`string`	—	Keyboard type hint, e.g. `"email"` or `"number"`.
`required`	`boolean`	`false`	Prevent advancing until the field is filled.
`backgroundColor`	`string`	—	Input field background (hex).
`borderColor`	`string`	—	Border color (hex).
`borderWidth`	`number`	—	Border width in pixels.
`borderRadius`	`number`	—	Corner radius in pixels.
`height`	`number`	—	Input height in pixels.
`color`	`string`	theme `textPrimary`	Text color (hex).

{
  "type": "text_input",
  "key": "name",
  "placeholder": "Your first name",
  "required": true
}

Slider

A horizontal numeric slider. Records the selected value under the block's key.

Property	Type	Default	Description
`type`	`"slider"`	—	Block type.
`key`	`string`	—	Required. Answer key.
`min`	`number`	—	Minimum value.
`max`	`number`	—	Maximum value.
`step`	`number`	—	Step increment.
`default_value`	`number`	—	Initial slider position.

{
  "type": "slider",
  "key": "age",
  "min": 18,
  "max": 80,
  "step": 1,
  "default_value": 30
}

Benefits List

An icon-labeled list of benefit items. Use it for feature highlights or value propositions.

Property	Type	Default	Description
`type`	`"benefits_list"`	—	Block type.
`items`	`{ text: string }[]`	—	List items.
`icon`	`string`	—	Lucide icon name applied to all items, e.g. `"Check"`.
`iconColor`	`string`	theme `primary`	Icon color (hex).
`iconSize`	`number`	`16`	Icon size in pixels (8–64).
`color`	`string`	theme `textPrimary`	Item text color (hex).
`fontSize`	`number`	—	Item text size in pixels.

{
  "type": "benefits_list",
  "icon": "Check",
  "iconColor": "#6EBA81",
  "items": [
    { "text": "Personalized workout plans" },
    { "text": "Progress tracking" },
    { "text": "Expert coaching" }
  ]
}

Testimonial

A customer quote with attribution. Use it to build social proof.

Property	Type	Default	Description
`type`	`"testimonial"`	—	Block type.
`quote`	`string`	—	Testimonial text.
`author`	`string`	—	Name of the person quoted.
`meta`	`string`	—	Additional context, e.g. job title or review source.
`backgroundColor`	`string`	theme `surface`	Card background (hex).
`borderRadius`	`number`	—	Corner radius in pixels.
`color`	`string`	theme `textPrimary`	Quote text color (hex).

{
  "type": "testimonial",
  "quote": "I lost 12 pounds in the first month. Best app I've ever used.",
  "author": "Sarah M.",
  "meta": "Verified user"
}

CTA

One or two action buttons. CTA buttons drive navigation between screens and mark flows as complete. Sticky by default.

Property	Type	Default	Description
`type`	`"cta"`	—	Block type.
`primary`	`CTAAction`	—	Primary (main) button.
`secondary`	`CTAAction`	—	Secondary button below the primary.
`sticky`	`boolean`	`true`	Attach to the bottom of the screen.
`height`	`number`	—	Button height in pixels.
`backgroundColor`	`string`	theme `primary`	Primary button background (hex).
`borderRadius`	`number`	—	Button corner radius in pixels.

CTAAction

Property	Type	Description
`label`	`string`	Button label text.
`action`	`"next" \| "back" \| "skip" \| "close" \| "complete"`	Navigation action on tap. Use `"complete"` to end the flow and fire `onComplete`.
`target`	`string`	Screen ID to navigate to directly, bypassing sequential order.

{
  "type": "cta",
  "primary": { "label": "Continue", "action": "next" },
  "secondary": { "label": "Skip for now", "action": "skip" }
}

Progress Bar

A horizontal progress indicator. Progress is calculated from the user's current screen index relative to total screens.

Property	Type	Default	Description
`type`	`"progress_bar"`	—	Block type.
`fillColor`	`string`	theme `primary`	Filled portion color (hex).
`fillOpacity`	`number`	`100`	Fill opacity, 0–100.
`backgroundColor`	`string`	theme `surface`	Track background (hex).
`borderRadius`	`number`	—	Corner radius in pixels.
`height`	`number`	—	Bar height in pixels.

{
  "type": "progress_bar",
  "fillColor": "#6EBA81",
  "height": 8,
  "borderRadius": 4
}

Personalization

A timed sequence of text strings that cycle automatically. Use it to enumerate personalized benefits while the user waits.

Property	Type	Default	Description
`type`	`"personalization"`	—	Block type.
`items`	`PersonalizationItem[]`	—	Required. Ordered items to cycle through.
`key`	`string`	—	Optional answer key to record which item was last shown.

PersonalizationItem

Property	Type	Description
`text`	`string`	Text to display.
`durationMs`	`number`	Display duration in milliseconds (500–60,000).

{
  "type": "personalization",
  "items": [
    { "text": "Analyzing your goals...", "durationMs": 1500 },
    { "text": "Building your plan...", "durationMs": 1500 },
    { "text": "Almost ready!", "durationMs": 1000 }
  ]
}

Spacer

Inserts vertical whitespace between blocks.

Property	Type	Default	Description
`type`	`"spacer"`	—	Block type.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	—	Token-based size.
`height`	`number`	—	Exact height in pixels. Takes precedence over `size`.

{ "type": "spacer", "size": "md" }

Small text at the bottom of a screen. Rendered at 12px, centered, in the theme's textSecondary color.

Property	Type	Description
`type`	`"footer"`	Block type.
`text`	`string`	Footer text.

{
  "type": "footer",
  "text": "By continuing you agree to our Terms of Service and Privacy Policy."
}