NutrientInstantView widget

NutrientInstantView embeds a live collaborative PDF document directly in your Flutter widget tree. It connects to a Nutrient Document Engine server and renders the document with real-time annotation syncing, so multiple users can see each other’s changes.

Platform support: Android and iOS. Web renders a placeholder.

Server setup

Before you use the NutrientInstantView widget, set up a running Document Engine instance and create a signed JSON Web Token (JWT) for the target document. Refer to these guides for setup details:

• Document Engine getting started
• Real-time collaboration with Instant syncing
• Generate a JWT

Basic usage

Add the widget to your widget tree. Set serverUrl to the document URL on your Document Engine instance and pass a signed JWT. The widget fills its available space, so wrap it in Expanded, SizedBox, or another layout widget.

NutrientInstantView(
  serverUrl: 'https://your-server.example.com/api/1/documents/ABC123',
  jwt: 'eyJhbGci...',
  onViewCreated: (NutrientViewHandle handle) {
    // The native view is ready. Store the handle for programmatic access
    // to annotations, page navigation, and other document operations.
  },
)

Constructor parameters

Use these parameters to configure the Instant document connection, viewer behavior, and controller lifecycle.

The Instant controller

onControllerReady surfaces a NutrientInstantController(opens in a new tab). This controller provides the regular controller surface, such as document and events, plus Instant sync controls:

NutrientInstantView(
  serverUrl: serverUrl,
  jwt: jwt,
  onControllerReady: (controller) async {
    // Instant sync controls (Android and iOS):
    await controller.setDelayForSyncingLocalChanges(2); // Seconds.
    await controller.setListenToServerChanges(true);
    await controller.syncAnnotations();

    // Typed Instant events (buffered — no events are missed).
    controller.events.instantSyncFinished.listen((e) {
      print('In sync: ${e.documentId}');
    });
  },
)

On Web, these controls aren’t available. The Web SDK configures Instant sync at load time and manages syncing, and onControllerReady isn’t called.

Custom controllers

NutrientInstantView uses the same adapter model as NutrientDocumentView:

• Bare NutrientInstantView(...) — The platform creates the default Instant controller for this view and disposes it with the view.
• Typed NutrientInstantView<MyInstantController>(...) — The view creates an instance from the factory registered with Nutrient.addAdapterClass<MyInstantController>(...) and owns its lifecycle. MyInstantController must implement NutrientInstantController.
• Per-view instance with adapter: — You allocate and dispose the controller. The view only attaches and detaches it.

For more information about the adapter model, refer to the platform adapters guide.

Apply configuration

Use NutrientViewConfiguration to customize the viewer’s layout, user interface (UI), and editing capabilities. Platform-specific options are grouped under androidConfig and iosConfig:

NutrientInstantView(
  serverUrl: serverUrl,
  jwt: jwt,
  configuration: const NutrientViewConfiguration(
    pageLayoutMode: PageLayoutMode.single,
    thumbnailBarMode: ThumbnailBarMode.floating,
    enableAnnotationEditing: true,
    enableFormEditing: true,
    enableInstantComments: true,
    aiAssistantConfiguration: {
      'serverUrl': 'https://your-ai-assistant-server.com',
      'jwt': 'your-ai-assistant-jwt',
      'sessionId': 'unique-session-id',
    },
    androidConfig: AndroidViewConfiguration(
      showSearchAction: true,
      showOutlineAction: true,
    ),
    iosConfig: IOSViewConfiguration(
      spreadFitting: SpreadFitting.adaptive,
    ),
  ),
)

enableInstantComments and aiAssistantConfiguration only apply to Android and iOS Instant documents. For a complete list of options, refer to the view configuration guide.

Reconnect and change documents

serverUrl and jwt are fixed at construction time. The native SDK establishes the WebSocket connection once and doesn’t observe changes to these values. To switch to a different document or refresh an expired JWT, force the widget to rebuild by changing its key.

A common pattern stores an integer counter in state and increments it whenever new connection settings apply:

int _viewKey = 0;

void _applyNewConnection(String serverUrl, String jwt) {
  setState(() {
    _serverUrl = serverUrl;
    _jwt = jwt;
    _viewKey++; // Forces NutrientInstantView to rebuild with new values.
  });
}

NutrientInstantView(
  key: ValueKey(_viewKey),
  serverUrl: _serverUrl!,
  jwt: _jwt!,
)

Complete example

The instant_example in the Catalog app(opens in a new tab) shows a complete working example, including a connection sheet, a status indicator, and platform-specific configuration.