@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.

Param	Type
options	PresentOptions

Returns: Promise<PresentResult>

---

dismiss(...)

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

Dismiss a 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.

Param	Type
options	PushOptions

Returns: Promise<PushResult>

---

pop(...)

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

Pop the top component off a 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
type	'stack'
components	ViewSpec[]
bar	BarSpec
title	string

ViewSpec

Prop	Type	Description
type	'view'
path	string	The path representing the view.
state	ViewState
title	string
stackItem	StackItemSpec	Options for when the component is used in a stack

StackItemSpec

Prop	Type	Description
backItem	StackBarButtonItem
leftItems	StackBarButtonItem[]
rightItems	StackBarButtonItem[]
backEnabled	boolean	Enables the system gestures and buttons for managing the back action. Useful for preventing the user from exiting a window that is running an important operation. Does not prevent the user from backgrounding the application. Default behaviour is to use the host Stack configuration which behaves as backEnabled is true
bar	BarSpec	Customise the bar on top of the default options provided by the stack

StackBarButtonItem

Prop	Type
id	ButtonId
title	string
image	ImageSpec

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.

BarSpec

Prop	Type
background	FillSpec
title	LabelSpec
buttons	LabelSpec
visible	boolean

FillSpec

Prop	Type
color	string

LabelSpec

Prop	Type
color	string
font	FontSpec

FontSpec

Prop	Type
name	string
size	number

TabsSpec

Prop	Type
type	'tabs'
tabs	TabSpec[]
title	string

TabSpec

Prop	Type	Description
id	ComponentId	The id to use for the tab, or undefined to automatically generate an id.
title	string
image	ImageSpec
badgeValue	string
component	ViewSpec | StackSpec

DismissResult

Prop	Type
id	ComponentId

DismissOptions

Prop	Type
id	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	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	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	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

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

StackItemUpdate

Prop	Type	Description
backItem	StackBarButtonItem | null
leftItems	StackBarButtonItem[] | null
rightItems	StackBarButtonItem[] | null
backEnabled	boolean | null	Enables the system gestures and buttons for managing the back action. Useful for preventing the user from exiting a window that is running an important operation. Does not prevent the user from backgrounding the application. Default behaviour is to use the host Stack configuration which behaves as backEnabled is true
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	AnyComponentSpec	The component, if any.
stack	StackSpec	The stack containing the component, if any.
tabs	TabsSpec	The tabs containing the component, if any.

GetOptions

Prop	Type	Description
id	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

string

AnyComponentSpec

StackSpec | TabsSpec | ViewSpec

ViewState

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

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'