⌘K

Block

Blocks are the basic pieces that make up your app’s UI in Nativeblocks. Every block is just a part of your screen—like a button, text, or card. You decide how each block looks and works by setting its properties.

How does a Block work?

Here’s what usually happens:

  1. You define a block, giving it a key and various settings.
  2. You add the block to the NativeBlockProvider so the system knows about it.
  3. When the app runs, Nativeblocks finds your block and draws it using blockView(blockProps:).

BlockView

This is the function where you actually show a block on the screen. It’s a Composable, so it works with Jetpack Compose.

@Composable
fun BlockView(blockProps: BlockProps)

blockProps: The information the block needs to figure out what to show and how to behave.

BlockProps

Represents the properties required for rendering and handling a native block.

/**
 * Represents the properties required for rendering and handling a native block.
 * @param instanceName instance name of NativeblocksManager.
 * @param listItemIndex Index of the list item associated with the block (optional).
 * @param onFindVariable Lambda function for retrieving a [NativeVariableModel] by its key.
 * @param onVariableChange Callback invoked when a variable changes (optional).
 * @param onFindAction Lambda function for retrieving a [NativeActionModel] by its event type.
 * @param onHandleAction Callback invoked to handle an action with the given index, action model, and type (optional).
 * @param onLocalize Callback function to handle text localization, takes a string key and returns localized text or null (optional).
 * @param block The model representing the block to be rendered (optional).
 * @param hierarchy List representing the hierarchy of the block within its parent-child relationship. Can be `null`.
 * @param onSubBlock Composable callback to render sub-blocks within the specified slot and index (optional).
 */
data class BlockProps(
    val instanceName: String,
    val listItemIndex: Int,
    val onFindVariable: (String) -> NativeVariableModel?,
    val onVariableChange: (NativeVariableModel) -> Unit,
    val onFindAction: (String) -> NativeActionModel?,
    val onHandleAction: (Int, NativeActionModel?, String) -> Unit,
    val onLocalize: (String) -> String?,
    val block: NativeBlockModel?,
    val hierarchy: List<NativeBlockHierarchyModel>,
    val onSubBlock: @Composable (blocks: Map<String, NativeBlockModel>, slot: NativeBlockSlotModel, index: Int, scope: Any?) -> Unit
)
  • instanceName: The unique instance name for the NativeblocksManager.
  • listItemIndex: The index if your block is part of a list.
  • onFindVariable: Lambda to get a variable (NativeVariableModel) by its key.
  • onVariableChange: Callback when a variable changes.
  • onFindAction: Lambda to get an action (NativeActionModel) by event type.
  • onHandleAction: Callback to handle an action with the given list index, action, and type.
  • onLocalize: Lambda for text localization. Pass the string key, get the localized string (or null).
  • block: The NativeBlockModel representing the block.
  • hierarchy: The hierarchy list showing where this block sits in the parent-child relationship.
  • onSubBlock: Composable callback to render sub-blocks for a specific slot, index, and (optionally) scope.

NativeBlockModel

This is the main data model for a block. It has everything you need to describe a block.

data class NativeBlockModel

What’s included:

  • id: The unique id of the block.
  • parentId: If this block belongs to another, that's its id.
  • slot: If the block sits in a named slot (think of it like a drawer or area), this is its name.
  • keyType: The type that tells you what kind of block this is (like "row", "button", etc).
  • key: A key used to identify your block.
  • visibility: Is the block showing or hidden? ("visible", "hidden" etc).
  • position: Where this block sits compared to others.
  • data: Any extra data you want with your block.
  • properties: The settings for your block, and how they appear on different devices (mobile/tablet/desktop).
  • slots: Places inside this block where other content or blocks can go.
  • subBlocks: The child blocks inside this block, mapped by id.

NativeBlockPropertyModel

This describes one property (setting) for a block, and its value on different devices.

data class NativeBlockPropertyModel

What’s inside:

  • key: The name of the property (like "backgroundColor").
  • valueMobile: What value the property should have on mobile.
  • valueTablet: The value to use on tablets.
  • valueDesktop: What to show on desktops.
  • type: What kind of property this is (like "string", "boolean").

NativeBlockDataModel

If your block needs to hold some data, this model describes one piece of it.

data class NativeBlockDataModel
  • key: What the data is called.
  • value: The data itself.
  • type: Type for the data (is it a string, a number, etc).

NativeBlockSlotModel

Sometimes a block has slots—places where other stuff can go (like a row has slots for children).

data class NativeBlockSlotModel
  • slot: The name of the slot (for example, "header", "footer").

NativeBlockHierarchyModel

Blocks are often nested, and this model explains how one block sits inside others.

data class NativeBlockHierarchyModel
  • key: Unique name of the block.
  • position: Where this block sits within its container.
  • hierarchyPosition: Number showing its place in the block hierarchy.
  • keyType: Type of block (for example, "row" or "box").
  • slot: Slot name for this block, if any.
  • scope: The parent block's scope (context).