Skip to main content
This document describes how to programmatically navigate to pages and fields within a form using the goto API on Navigator.

​
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
Instantiate Navigator and pass it to the JoyDoc component via the navigator prop. Then call navigator.goto(path) with a path string whenever you want to navigate. 
import { JoyDoc, Navigator } from '@joyfill/components';

const navigator = new Navigator();

<JoyDoc navigator={navigator} doc={doc} mode="fill" />

// Later, from your code:
navigator.goto('page_123');
navigator.goto('page_123/fieldPosition_456');

​
Path-Based Navigation

Navigate using a slash-separated path string. 
// Navigate to a page
navigator.goto("page_123")

// Navigate to a field on a page (with auto-scroll)
navigator.goto("page_123/fieldPosition_456")
Path FormatDescription
"pageId"Navigate to the top of the specified page
"pageId/fieldPositionId"Navigate to the page and scroll to the field
Important: Use fieldPositionId from page.fieldPositions[]._id, not fieldId from document.fields[]._id. Using the wrong ID will cause navigation to fail.
The goto method returns an object indicating success or failure. 
const result = navigator.goto("page_123/fieldPosition_456")

if (result.status === "success") {
  // Navigation succeeded - target exists and is visible
} else {
  // Navigation failed - target doesn't exist, is hidden, or unsupported
}
ResponseDescription
"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 (e.g. file, unknown)
  • Navigating to a hidden field: the page still switches and scrolls to the top of the page, but status is "failure"

​
Page Change Events

Page changes triggered by goto() or by the user clicking a page in the UI are emitted through the onBlur and onFocus callbacks (the navigation listener). When the active page changes, the SDK fires a page event so you can track which page is focused. Check the type property on the event to distinguish page events from field focus/blur events: 
<JoyDoc
  doc={doc}
  onFocus={(params) => {
    if (params.type === 'page.focus') {
      console.log('Arrived at page:', params.page._id, params.page.name)
    }
  }}
  onBlur={(params) => {
    if (params.type === 'page.blur') {
      console.log('Left page:', params.page._id)
    }
  }}
/>
EventTrigger
onBlur with type: 'page.blur'Emitted when navigating away from a page
onFocus with type: 'page.focus'Emitted when navigating to a page
Page event payload:
PropertyDescription
sdk'js'
v1
type'page.focus' or 'page.blur'
_idDocument ID
identifierDocument identifier
fileIdFile ID
pageThe full page object that gained or lost focus
For all event options (including field-level focus/blur), see Event Handling.