Joyfill Kotlin Multiplatform SDK

Build once, run everywhere. Joyfill is a battle‑tested, production‑ready SDK with predictable APIs and fast rendering.

This repository contains:

compose — UI components to render and interact with Joyfill documents (JetBrains Compose)
models — document data model and JSON serialization
builder — DSL to construct Joyfill documents programmatically

Official docs: https://docs.joyfill.io/docs/kotlin

Getting Started

Overview

Joyfill documents (JoyDocs) are JSON‑schema‑based. You can:

Load a document from JSON and render it with Compose
Listen to user interactions and state changes
Validate fields and the full schema locally
Build documents programmatically with the DSL

Useful references:

Kotlin guide
API docs
./CHANGELOG.md
./docs/migration-guide.md
Formula docs
./samples

Install SDK

Add the dependency to your Gradle module. Check CHANGELOG.md for the latest version.

dependencies {
    implementation("io.joyfill:compose:<version>")
    // Optional:
    implementation("io.joyfill:api:<version>")
}

See migration notes in ./docs/migration-guide.md if you are upgrading from v1.

Load First Form

Download the sample JSON to get started without any API calls:

first-form.json: ./docs/first-form.json

Render it in Compose:

@Composable
fun FirstFormScreen(json: String) {
    Form(editor = rememberDocumentEditor(json))
}

If you are on Android/Desktop, you can load the file from assets/resources and pass its content string to rememberDocumentEditor.

Listen for form changes (Log changes)

You can observe focus/blur, file uploads, image capture, and all field changes. Logging changes is as simple as printing the events.

@Composable
fun JoyfillWithLogging(json: String) {
    Form(
        editor = rememberDocumentEditor(json),
        onFieldChange = { event ->
            // FieldEvent for simple components, CellEvent for table cells
            println("Changed -> page=${event.page.id} source=${event.source?.id} fileId=${event.fileId}")
        },
        onFocus = { event -> println("Focus -> page=${event.page.id} source=${event.source?.id}") },
        onBlur = { event -> println("Blur -> page=${event.page.id} source=${event.source?.id}") }
    )
}

Link to code example repos

Kotlin samples in this repository: samples

BuiltIn Functions

Use Wisdom formulas to compute values from other fields (e.g., sums, conditions). See docs: joyfill.io

Image Uploads

Handle uploads via the onUpload callback and return hosted URLs.

onUpload = { event: ComponentEvent<AbstractFileEditor> ->
    // Upload files from event.request and return one or more URLs
    listOf("https://your.cdn/uuid.jpg")
}

Field Validation

Run field‑level checks via editor.validate() which returns FieldsValidity. You can also add required rules and constraints directly in the JSON schema.

val validity: FieldsValidity = editor.validate()

Schema Validation

Validate a JoyDoc JSON string locally before rendering:

val validationError: SchemaError? = JoyfillSchemaManager.validateSchema(joyDocJson)
if (validationError != null) {
    println("Invalid schema: ${validationError.message}")
}

There is also a convenience extension on Document: Document.validateSchema().

Form schema validation (validateSchema)

The Document editor has a validateSchema flag pass it to rememberDocumentEditor/editorOf. It is true by default and will surface an error UI if the schema is invalid.

val editor = editorOf(
    json = joyDocJson,
    // Use this to disable schema validation
    validateSchema = false, // default: true
)
// or
val editor = rememberDocumentEditor(
    json = joyDocJson,
    // Use this to disable schema validation
    validateSchema = false, // default: true
)