Capacitor-native-navigation NPM

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(...)

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

{

}

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'