Capacitor Native Navigation Plugin

Native navigation for Capacitor apps.

This package provides a Capacitor plugin for controlling native navigation UI from a React DOM app.

Please see the root of this repository for a discussion of how to use this plugin.

Install

npm install @cactuslab/native-navigation
npx cap sync

API

• present(...)
• dismiss(...)
• push(...)
• pop(...)
• update(...)
• reset(...)
• get(...)
• message(...)
• Interfaces
• Type Aliases

present(...)

present(options: PresentOptions) => Promise<PresentResult>

Present a new native UI.

See dismiss for removing the presentation

| Param | Type | | ------------- | --------------------------------------------------------- | | options | PresentOptions |

Returns: Promise<PresentResult>

dismiss(...)

dismiss(options?: DismissOptions | undefined) => Promise<DismissResult>

Dismiss a native UI. The component id may be a component that was previously presented or a component within a previously presented component.

See present for presenting native UI.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | DismissOptions |

Returns: Promise<DismissResult>

push(...)

push(options: PushOptions) => Promise<PushResult>

Push a new component onto a stack, or replace an existing component.

See pop for removing a component from the stack.

| Param | Type | | ------------- | --------------------------------------------------- | | options | PushOptions |

Returns: Promise<PushResult>

pop(...)

pop(options: PopOptions) => Promise<PopResult>

Pop the top component off a stack.

See push for adding a component to the stack.

| Param | Type | | ------------- | ------------------------------------------------- | | options | PopOptions |

Returns: Promise<PopResult>

update(...)

update(options: UpdateOptions) => Promise<void>

Set the options for an existing component

| Param | Type | | ------------- | ------------------------------------------------------- | | options | UpdateOptions |

reset(...)

reset(options?: ResetOptions | undefined) => Promise<void>

Remove all of the native UI and reset back to the root Capacitor webview.

| Param | Type | | ------------- | ----------------------------------------------------- | | options | ResetOptions |

get(...)

get(options?: GetOptions | undefined) => Promise<GetResult>

Get the spec and context of a component

| Param | Type | | ------------- | ------------------------------------------------- | | options | GetOptions |

Returns: Promise<GetResult>

message(...)

message<D>(options: MessageOptions<D>) => Promise<void>

Send a message to a component.

| Param | Type | | ------------- | ------------------------------------------------------------------ | | options | MessageOptions<D> |

Interfaces

PresentResult

| Prop | Type | | -------- | --------------------------------------------------- | | id | ComponentId |

PresentOptions

| Prop | Type | Description | | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | component | AnyComponentSpec | The component to present. | | style | PresentationStyle | The presentation style. Defaults to 'fullScreen' | | cancellable | boolean | Whether to allow the user to use system gestures or the back button to unwind the presentation. Useful to prevent the accidental dismissal of a form. Defaults to true | | animated | boolean | Whether to animate the presenting. Defaults to true |

StackSpec

| Prop | Type | Description | | ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------- | | type | 'stack' | | | components | ViewSpec[] | | | bar | BarSpec | | | title | string | | | state | StateObject | State that will be mixed into the state of each of the contained components |

ViewSpec

| Prop | Type | Description | | --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | 'view' | | | path | string | The path representing the view. | | state | StateObject | | | title | string | The title is shown in the title bar when the view is shown in a stack. Titles may also be used in other ways by the native environment and are a good idea. | | stackItem | StackItemSpec | Options for when the component is used in a stack | | android | { backButtonId?: string; } | Options for Android specific features |

StackItemSpec

| Prop | Type | Description | | ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | backItem | StackBarButtonItem | The back item used when this stack item is on the back stack. This is only currently used by iOS as Android will show an arrow with no title if back is enabled | | leftItems | StackBarButtonItem[] | Setting any value to leftItems will disable the navigation back buttons on both iOS and Android. (Android hardware back button is not affected). iOS: items will show on the left side of the navigation bar replacing the back button. The swipe back gesture will be disabled. Android: Toolbars have support for only a single image-button on the left. If the first item has an image then the toolbar will insert this item left of the title replacing the default back button if there would have been one. The remaining left items will appear on the right of the toolbar ahead of any right items. | | rightItems | StackBarButtonItem[] | Right items will show on the rightmost edge of the navigation bar. | | bar | BarSpec | Customise the bar on top of the default options provided by the stack |

StackBarButtonItem

| Prop | Type | Description | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- | | id | ButtonId | | | title | string | A title for the button or context for a screen reader if the button has an icon | | image | ImageSpec | If image is present then the title will be replaced by the image | | android | { image?: ImageSpec; } | Custom options for Android specific behaviours |

ImageObject

| Prop | Type | Description | | ----------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | uri | string | The uri for the image. | | scale | number | The scale to use for the image, e.g. 2 for a 2x scale image. If not provided the scale will be determined automatically from the filename, or it will default to 1. | | disableTint | boolean | By default if this image is used in a button it will get tinted the color of the button. If your image needs to keep its original colors set disableTint: true to prevent the tinting. |

BarSpec

| Prop | Type | | ---------------- | ------------------------------------------------- | | background | FillSpec | | title | LabelSpec | | buttons | LabelSpec | | visible | boolean | | iOS | BarSpecIOS |

FillSpec

| Prop | Type | | ----------- | ------------------- | | color | string |

LabelSpec

| Prop | Type | | ----------- | --------------------------------------------- | | color | string | | font | FontSpec |

FontSpec

| Prop | Type | | ---------- | ------------------- | | name | string | | size | number |

BarSpecIOS

| Prop | Type | Description | | ---------------- | ---------------------------- | --------------------------------------- | | hideShadow | boolean | null | Default behaviour is to show the shadow |

TabsSpec

| Prop | Type | Description | | ----------- | --------------------------------------------------- | --------------------------------------------------------------------------- | | type | 'tabs' | | | tabs | TabSpec[] | | | title | string | | | state | StateObject | State that will be mixed into the state of each of the contained components |

TabSpec

| Prop | Type | Description | | ---------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | alias | ComponentAlias | | | title | string | | | image | ImageSpec | | | badgeValue | string | | | component | ViewSpec | StackSpec | | | state | StateObject | State that will be mixed into the state of each of the contained components |

DismissResult

| Prop | Type | | -------- | --------------------------------------------------- | | id | ComponentId |

DismissOptions

| Prop | Type | | -------------- | ------------------------------------------------------------- | | id | string | ComponentId | | animated | boolean |

PushResult

| Prop | Type | Description | | ----------- | --------------------------------------------------- | ---------------------------------------------------------- | | id | ComponentId | The id of the component that was pushed. | | stack | ComponentId | The stack that was pushed to, if it was pushed to a stack. |

PushOptions

| Prop | Type | Description | | --------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | component | ViewSpec | The options for the view to push onto the stack. | | target | string | ComponentId | The target component to push to, usually a stack, or undefined to push to the current stack or component. | | animated | boolean | Whether to animate the push. Defaults to true | | mode | PushMode | The mode to use for the push. Defaults to 'push'. push: Push the component onto the stack. replace: Replace the current top-most component in the stack. root: Reset the stack back to just the new component. | | popCount | number | How many items to pop first |

PopResult

| Prop | Type | Description | | ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | stack | ComponentId | | | count | number | The number of components that were popped | | id | ComponentId | The id of the component that was popped, if any. If multiple components are popped, the id will be of the last component popped. |

PopOptions

| Prop | Type | Description | | -------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ | | stack | string | ComponentId | The stack to pop from, or undefined to pop from the current stack. | | count | number | How many items to pop | | animated | boolean | Whether to animate the pop. Defaults to true |

UpdateOptions

| Prop | Type | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | id | string | ComponentId | | | animated | boolean | Whether to animate the changes. Defaults to false | | update | StackUpdate | TabsUpdate | TabUpdate | ViewUpdate | |

StackUpdate

Options for stack components

| Prop | Type | | ---------------- | ----------------------------------------------- | | components | ViewSpec[] | | bar | BarUpdate |

BarUpdate

| Prop | Type | | ---------------- | ----------------------------------------------------------- | | background | FillUpdate | null | | title | LabelUpdate | null | | buttons | LabelUpdate | null | | visible | boolean | null | | iOS | BarSpecIOS |

FillUpdate

| Prop | Type | | ----------- | --------------------------- | | color | string | null |

LabelUpdate

| Prop | Type | | ----------- | --------------------------------------------------------- | | color | string | null | | font | FontUpdate | null |

FontUpdate

| Prop | Type | | ---------- | --------------------------- | | name | string | null | | size | number | null |

TabsUpdate

Options for tabs components

| Prop | Type | | ---------- | ---------------------- | | tabs | TabSpec[] |

TabUpdate

| Prop | Type | | ---------------- | ----------------------------------------------------------------------------------- | | title | string | null | | image | ImageSpec | null | | badgeValue | string | null | | component | ViewSpec | StackSpec |

ViewUpdate

Options for view components

| Prop | Type | Description | | --------------- | ----------------------------------------------------------- | ------------------------------------------------- | | stackItem | StackItemUpdate | Options for when the component is used in a stack | | android | { backButtonId?: string | null; } | Options for Android specific features |

StackItemUpdate

| Prop | Type | Description | | ---------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | backItem | StackBarButtonItem | null | The back item used when this stack item is on the back stack. This is only currently used by iOS as Android will show an arrow with no title if back is enabled | | leftItems | StackBarButtonItem[] | null | Setting any value to leftItems will disable the navigation back buttons on both iOS and Android. (Android hardware back button is not affected). iOS: items will show on the left side of the navigation bar replacing the back button. The swipe back gesture will be disabled. Android: Toolbars have support for only a single image-button on the left. If the first item has an image then the toolbar will insert this item left of the title replacing the default back button if there would have been one. The remaining left items will appear on the right of the toolbar ahead of any right items. | | rightItems | StackBarButtonItem[] | null | Right items will show on the rightmost edge of the navigation bar. | | bar | BarUpdate | null | Customise the bar on top of the default options provided by the stack |

ResetOptions

| Prop | Type | Description | | -------------- | -------------------- | --------------------------------------------------------------------------------- | | animated | boolean | Whether to animate resetting the navigation back to Capacitor Defaults to false |

GetResult

| Prop | Type | Description | | --------------- | --------------------------------------------------------------- | ------------------------------------------- | | component | AnyComponentModel | The component, if any. | | stack | StackModel | The stack containing the component, if any. | | tabs | TabsModel | The tabs containing the component, if any. |

StackModel

| Prop | Type | | -------- | --------------------------------------------------- | | id | ComponentId |

TabsModel

| Prop | Type | | -------- | --------------------------------------------------- | | id | ComponentId |

ViewModel

| Prop | Type | | -------- | --------------------------------------------------- | | id | ComponentId |

GetOptions

| Prop | Type | Description | | -------- | ------------------------------------------------------------- | -------------------------------------------------------------------- | | id | string | ComponentId | The component id to get, or undefined to get the top-most component. |

MessageOptions

| Prop | Type | Description | | ------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------- | | target | ComponentId | The target component of the message, or undefined to send to the top-most component. | | type | string | The message type. | | value | D | A message value. Must be JSON stringifiable. |

Type Aliases

ComponentId

Opaque<'ComponentId', string>

Opaque

T & { TYPE: K }

AnyComponentSpec

StackSpec | TabsSpec | ViewSpec

StateObject

Record<string, string | number | boolean | null>

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

ButtonId

string

ImageSpec

ImageObject | string

ComponentAlias

string

PresentationStyle

'fullScreen' | 'pageSheet' | 'formSheet' | 'dialog'

PushMode

push: Push the component onto the stack. replace: Replace the current top-most component in the stack. root: Reset the stack back to just the new component.

'push' | 'replace' | 'root'

AnyComponentModel

StackModel | TabsModel | ViewModel