> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joyfill.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation

This document describes how to programmatically navigate to pages, fields, table/collection rows, and individual cells within a form using the `goto` API on `DocumentEditor`.

## Overview

The `goto` method enables programmatic navigation to specific locations within a form. This is useful for:

* Guiding users to required fields after validation
* Implementing custom navigation flows
* Deep linking to specific form sections
* Auto-scrolling to specific fields
* Opening a specific table or collection row in its row form (modal)
* Focusing a specific cell within a table or collection row

## Path-Based Navigation

Navigate using a slash-separated path string. Up to four segments are supported.

```kotlin theme={null}
// Navigate to a page
editor.goto("page_123")

// Navigate to a field on a page
editor.goto("page_123/fieldPos_456")

// Navigate to a row on a table/collection field on a page
editor.goto("page_123/fieldPos_456/row_1")

// Navigate to a row and open the row form modal
editor.goto("page_123/fieldPos_456/row_1", GotoConfig(open = true))


// Navigate to a specific cell in a table or collection row
editor.goto("page_123/fieldPosition_456/row_789/column_012", GotoConfig(open: true, focus: true))
```

| Path Format                               | Description                                                                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"pageId"`                                | Navigate to the top of the specified page                                                                                                                            |
| `"pageId/fieldPositionId"`                | Navigate to the page and scroll to the field                                                                                                                         |
| `"pageId/fieldPositionId/rowId"`          | Navigate to the page, scroll to the table/collection field, and select the row. Use `GotoConfig(open = true)` to also open the row form modal.                       |
| `"pageId/fieldPositionId/rowId/columnId"` | Navigate to the page, scroll to the table/collection field, select the row, and target a specific column/cell. Use `GotoConfig(focus: true)` to auto-focus the cell. |

<Warning>
  **Important:** Use `fieldPositionId` from `page.fieldPositions[]._id`, not `fieldId` from `document.fields[]._id`. Using the wrong ID will cause navigation to fail.
</Warning>

For row-level paths, the field must be a **table** or **collection** type. The `rowId` must match an existing row's ID in that field's value; otherwise `goto` returns `.failure`.

For column-level paths, the `columnId` must match an existing visible column in the field; otherwise `goto` returns `.failure` (but still navigates to the row).

## GotoConfig

Navigation behavior is configured via `GotoConfig`. Pass it as the second argument to `goto`.

```kotlin theme={null}
/**
 * Configuration for [DocumentEditor.goto] navigation.
 *
 * @param open If true, automatically open row form when navigating to a row.
 *             Only applies to table/collection row navigation; ignored otherwise.
 * @param animate Whether to animate the scroll. Defaults to true.
 */
class GotoConfig(
    val open: Boolean = false,
    val focus: Boolean = false,
    val animate: Boolean = true
) {
    companion object {
        val default = GotoConfig()
    }
}
```

| Property  | Default | Description                                                                                                                                     |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`    | `false` | When `true`, automatically opens the row form modal for table/collection rows                                                                   |
| `animate` | `true`  | Whether to animate the scroll                                                                                                                   |
| `focus`   | `false` | When `true`, triggers the SDK's `onFocus` event for the target field or cell. For text, number, and barcode cells this also opens the keyboard. |

## NavResponse

The `goto` method returns a `NavResponse` indicating success or failure.

```kotlin theme={null}
val response = editor.goto("page_123/fieldPos_456")

when (response) {
    is NavResponse.Success -> {
        // Navigation succeeded - target exists and is visible
    }
    is NavResponse.Failure -> {
        // Navigation failed - target doesn't exist, is hidden, or unsupported
    }
}
```

| Response  | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| `Success` | The target exists, is supported, and is visible                        |
| `Failure` | The target does not exist, is hidden, or has an unsupported field type |

**Failure reasons include:**

* Page does not exist
* Page is hidden (due to conditional logic)
* Field position does not exist
* Field is hidden (due to conditional logic)
* Field type is unsupported (`file`, `unknown`)
* Row is hidden
* Row does not exist
* Column is hidden
* Column does not exist

## Page Change Events

Page changes triggered by `goto()` are emitted through the `onBlur` and `onFocus` callbacks. When the user navigates from one page to another (either via `goto()` or manual navigation), the callbacks receive a `ComponentEvent.PageEvent`:

```kotlin theme={null}
Form(
    editor = editor,
    onBlur = { event ->
        if (event is ComponentEvent.PageEvent) {
            // User left this page
            println("Left page: ${event.pageId}")
        }
    },
    onFocus = { event ->
        if (event is ComponentEvent.PageEvent) {
            // User arrived at this page
            println("Arrived at page: ${event.pageId}")
        }
    }
)
```

| Event                      | Trigger                                  |
| -------------------------- | ---------------------------------------- |
| `onBlur` with `PageEvent`  | Emitted when navigating away from a page |
| `onFocus` with `PageEvent` | Emitted when navigating to a page        |

**`PageEvent` Properties:**

| Property | Type     | Description                               |
| -------- | -------- | ----------------------------------------- |
| `page`   | `Page`   | The page object that gained or lost focus |
| `pageId` | `String` | The page ID                               |