plugin

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 capacitor-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
iOS	{ preventBounce?: boolean; }	Options for iOS 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	Description
color	string	A color to use for the background.

LabelSpec

Prop	Type
color	string
font	FontSpec

FontSpec

Prop	Type
name	string
size	number

BarSpecIOS

Prop	Type	Description
hideShadow	boolean	Default behaviour is to show the shadow
translucent	boolean	A flag to indicate Apple's translucency behaviour when content is scrolled. It can be used in conjunction with onScroll colors

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

Array

Prop	Type	Description
length	number	Gets or sets the length of the array. This is a number one higher than the highest index in the array.

Method	Signature	Description
toString	() => string	Returns a string representation of an array.
toLocaleString	() => string	Returns a string representation of an array. The elements are converted to string using their toLocalString methods.
pop	() => T | undefined	Removes the last element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.
push	(...items: T[]) => number	Appends new elements to the end of an array, and returns the new length of the array.
concat	(...items: ConcatArray<T>[]) => T[]	Combines two or more arrays. This method returns a new array without modifying any existing arrays.
concat	(...items: (T | ConcatArray<T>)[]) => T[]	Combines two or more arrays. This method returns a new array without modifying any existing arrays.
join	(separator?: string | undefined) => string	Adds all the elements of an array into a string, separated by the specified separator string.
reverse	() => T[]	Reverses the elements in an array in place. This method mutates the array and returns a reference to the same array.
shift	() => T | undefined	Removes the first element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.
slice	(start?: number | undefined, end?: number | undefined) => T[]	Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
sort	(compareFn?: ((a: T, b: T) => number) | undefined) => this	Sorts an array in place. This method mutates the array and returns a reference to the same array.
splice	(start: number, deleteCount?: number | undefined) => T[]	Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
splice	(start: number, deleteCount: number, ...items: T[]) => T[]	Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
unshift	(...items: T[]) => number	Inserts new elements at the start of an array, and returns the new length of the array.
indexOf	(searchElement: T, fromIndex?: number | undefined) => number	Returns the index of the first occurrence of a value in an array, or -1 if it is not present.
lastIndexOf	(searchElement: T, fromIndex?: number | undefined) => number	Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present.
every	<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => this is S[]	Determines whether all the members of an array satisfy the specified test.
every	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean	Determines whether all the members of an array satisfy the specified test.
some	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean	Determines whether the specified callback function returns true for any element of an array.
forEach	(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any) => void	Performs the specified action for each element in an array.
map	<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any) => U[]	Calls a defined callback function on each element of an array, and returns an array that contains the results.
filter	<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => S[]	Returns the elements of an array that meet the condition specified in a callback function.
filter	(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => T[]	Returns the elements of an array that meet the condition specified in a callback function.
reduce	(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T) => T	Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduce	(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T) => T
reduce	<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => U	Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRight	(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T) => T	Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRight	(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T) => T
reduceRight	<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => U	Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

ConcatArray

Prop	Type
length	number

Method	Signature
join	(separator?: string | undefined) => string
slice	(start?: number | undefined, end?: number | undefined) => T[]

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

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'

BarUpdate

RecursiveNullable<BarSpec>

RecursiveNullable

{ [K in keyof T]: Required<T>[K] extends object ? Required<T>[K] extends Array<infer U> ? Array<U> | null : RecursiveNullable<T[K]> : T[K] | null }

Required

Make all properties in T required

{ [P in keyof T]-?: T[P]; }

StackItemUpdate

RecursiveNullable<StackItemSpec>

AnyComponentModel

StackModel | TabsModel | ViewModel