Skip to main content

Data Values

Type-safe data containers and property types for ViewModel binding.

DataValue​

Type-safe wrapper for storing typed values in inputs.

Static Constructors​

DataValue.number()​

Creates a numeric data value container.

DataValue.number(): DataValueNumber

DataValue.string()​

Creates a string data value container.

DataValue.string(): DataValueString

DataValue.boolean()​

Creates a boolean data value container.

DataValue.boolean(): DataValueBoolean

DataValue.color()​

Creates a color data value container.

DataValue.color(): DataValueColor

Type Checking Methods​

MethodReturns true when...
dv:isNumber()Container holds a number
dv:isString()Container holds a string
dv:isBoolean()Container holds a boolean
dv:isColor()Container holds a Color

Example:

local val = DataValue.number()
print(val:isNumber())   -- true
print(val:isString())   -- false

See Also: Converter, DataValueNumber

DataValueNumber​

A DataValue that stores a numeric value.

Attributes​

value​

The numeric value. Type: number (read/write)

Example​

local dv: DataValueNumber = DataValue.number()
dv.value = 200

See Also: DataValue

DataValueString​

A DataValue that stores a string value.

Attributes​

value​

The string value. Type: string (read/write)

Example​

local dv: DataValueString = DataValue.string()
dv.value = "Hello Rive"

See Also: DataValue

DataValueBoolean​

A DataValue that stores a boolean value.

Attributes​

value​

The boolean value. Type: boolean (read/write)

Example​

local dv: DataValueBoolean = DataValue.boolean()
dv.value = true

See Also: DataValue

DataValueColor​

A DataValue that stores a color value with RGBA components.

Attributes​

AttributeTypeDescription
valuenumberFull encoded color value
rednumberRed component (0-255)
greennumberGreen component (0-255)
bluenumberBlue component (0-255)
alphanumberAlpha component (0-255)

Example​

local dv: DataValueColor = DataValue.color()
dv.value = Color.rgba(255, 0, 0, 255)
-- Or access individual components:
dv.red = 255
dv.green = 128
dv.blue = 0
dv.alpha = 255

See Also: DataValue, Color

Asset-valued properties​

ViewModel properties can carry opaque asset values in the target runtime. These are distinct from strings, buffers, and editor asset IDs.

Property<Font>​

Property<Font> reads an opaque Font userdata or nil:

local fontProperty: Property<Font>? = viewModel:getFont("font")
if fontProperty then
    local font = fontProperty.value
    if font then
        textStyle.fontAssetId = font
    end
end

The Luau setter accepts another Font userdata. It does not accept a string, buffer, or nil; a native host may clear the value with a null font. Keep the property handle alive when registering listeners.

Property<Blob>​

Property<Blob> reads a Blob?; the runtime accepts a Blob, buffer, string, or nil. In the current editor type checker, use an explicit any cast for these writable input forms:

local payload: Property<Blob>? = viewModel:getBlob("payload")
if payload then
    local writable = payload :: any
    writable.value = buffer.fromstring("hello")
    writable.value = "raw bytes"
    local blob = payload.value
    if blob and blob.data then
        print(blob.name, blob.size, buffer.readu8(blob.data, 0))
    end
    writable.value = nil -- clear the bound value
end

Without that cast, the editor reports Expected this to be Blob for string, buffer, and nil assignments even though the runtime accepts them. A focused Rive Beta 0.8.5390 (build 5377) probe passed getBlob, getFont, getImage, missing/null handling, and all three Blob assignment forms after the explicit cast. This remains editor-lane evidence rather than an exported Web 2.42.1 execution result.

An empty string or empty buffer is a real zero-byte Blob, not nil. The Blob.name, Blob.size, and Blob.data fields are the data-access surface; there are no implied Blob mutation methods.

Converter​

Transforms values between ViewModel data bindings and Rive properties.

Type Parameters​

  • T: The converter type
  • I: Input type (DataValue variant)
  • O: Output type (DataValue variant)

Protocol Methods​

init(self, context): boolean​

Called once when converter is created.

function init(self: MyConverter, context: Context): boolean
    return true
end

convert(self, input): O​

Transforms input to output.

function convert(self: MyConverter, input: DataValueNumber): DataValueString
    return DataValue.string()  -- Return converted value
end

reverseConvert(self, output): I​

Inverse transformation.

function reverseConvert(self: MyConverter, output: DataValueString): DataValueNumber
    return DataValue.number()
end

advance(self, seconds): boolean​

Optional per-frame update.

See Also: DataValue

PropertyList​

Dynamic list property with array-like operations.

Attributes​

list.length​

Number of items in the list. Type: number (read-only)

list[index]​

Indexed access to list items using 1-based indexing.

Methods​

list:push(item)​

Adds item to end of list.

list:pop()​

Removes and returns last item.

list:shift()​

Removes and returns first item.

list:insert(vm, index)​

Inserts a ViewModel instance at the specified position.

list:insert(vm: ViewModel, index: number)

list:remove(vm)​

Removes the first matching ViewModel instance from the list.

list:remove(vm: ViewModel)

list:removeAt(index)​

Removes the item at a 1-based index.

list:removeAt(index: number)
Bounds behavior

removeAt errors when index is out of range. Validate index >= 1 and index <= list.length before calling.

list:removeAllOf(vm)​

Removes all instances matching the given ViewModel.

list:removeAllOf(vm: ViewModel)

list:clear()​

Removes all items from the list.

list:swap(indexA, indexB)​

Exchanges two items' positions.

list:addListener(callback)​

Registers a callback for list change notifications.

list:addListener(callback: () -> ())

list:removeListener(callback)​

Removes a previously registered list change callback.

list:removeListener(callback: () -> ())

PropertyEnum​

Represents an enum property in a ViewModel.

Methods​

enum:values()​

Returns the available enum values.

enum:values(): EnumValues

See Also: EnumValues

PropertyTrigger​

Trigger property that fires events and notifies listeners.

Methods​

trigger:fire()​

Invokes the trigger, notifying all listeners.

trigger:fire()

trigger:addListener(callback)​

Registers a callback for trigger events.

trigger:addListener(callback: () -> ())

trigger:removeListener(callback)​

Removes a previously registered callback.

trigger:removeListener(callback: () -> ())

See Also: Trigger

PropertyViewModel​

ViewModel property wrapper (exposes the nested ViewModel via .value).

Attributes​

property.value​

The nested ViewModel. Type: ViewModel

See Also: ViewModel, Property

Next Steps​