@cactuslab/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 @cactuslab/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

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

{

}

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'