Portals Module

The @ionic/portals module is the main way to interface with a Portal instance. It has methods to easily pass messages back and forth to the native side via a publish/subscribe interface, and ways to pass data to a web view before it initializes.

Types

InitialContext

A type defining the InitialContext from the native application that you can pass into your web application.

interface InitialContext<T = unknown> {
  name: string;
  value?: T;
  assets?: {
    [key: string]: string;
  }
}

PortalMessage

A message that you can publish to a topic using publish.

interface PortalMessage<TData = any> {
  topic: string;
  data?: TData;
}

SubscribeOptions

Subscription options that you pass into your function when running subscribe.

interface SubscribeOptions {
  topic: string;
}

PortalSubscription

The subscription created when running subscribe.

interface PortalSubscription {
  subscriptionRef: number;
  topic: string;
}

SubscriptionCallback

The type definition from the callback running subscribe.

type SubscriptionCallback<T = unknown> = (result: {
  topic: string;
  data: T;
}) => void;

Methods

publish

Publishes some data to a provided topic. Type-safety supported through the optional TMessage generic type.

Usage

import { publish } from '@ionic/portals';

type Messages =
  | { topic: "cart:checkout"; data: Cart }
  | { topic: "modal:dismiss"; data: "cancel" | "fail" | "success" }
  | { topic: "profile:update"; data: User };

// Publishes "cancel" to the "dismiss" topic
publish<Messages>({ topic: "modal:dismiss", data: "cancel" });

Parameters

Name	Type	Description
message	PortalMessage	The PortalMessage object to publish to the native code.

subscribe

Subscribes to a topic and run a specified callback whenever a message is sent via publish.

Usage

import { subscribe } from '@ionic/portals';

const callback = (result: { topic: string; data: T }) => {
  /* run callback code here on publish */
};
const handle = await subscribe({ topic }, callback);
// call handle.remove() to stop receiving events

Parameters

Name	Type	Description
options	SubscribeOptions	The options to pass along to define the Portal subscription.
callback	SubscriptionCallback	The callback to trigger whenever a topic is published to.

Returns: Promise<PluginListenerHandle> A listener handle that provides a remove method to unsubscribe from the event.

getInitialContext

Gets the InitialContext of the Portal that was passed in from the native code.

Usage

// Passed in value is { foo: 'bar' }
import { getInitialContext } from '@ionic/portals';

const context = getInitialContext<{ foo: string }>;
console.log(context?.value?.foo); // bar

A real world example might be navigating to a route in a single page application

import { getInitialContext } from "@ionic/portals";

const context = getInitialContext<{ startingRoute: string }>();

ReactDOM.render(
  <React.StrictMode>
    <App context={context!.value} />
    {/* context.value = { startingRoute: '/help' } */}
  </React.StrictMode>,
  document.getElementById("root")
);

Returns: T | undefined The InitialContext value or undefined if it was not assigned.