@cactuslab/native-navigation

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