A set of hooks to help Capacitor developers use native Capacitor APIs.
| Maintainer | GitHub | Social |
|---|---|---|
| Ely Lucas | elylucas | @elylucas |
These docs are for Capacitor 3 plugins. For docs that target v2 plugins, see the capv2 branch.
To start using Capacitor Hooks in your app, you install the React Hook package along with the Capacitor plugin you want to use. Here is an example of using the Storage plugin along with it's React hook:
# Install the Capacitor Plugin
npm install @capacitor/storage
# And then the React hook package:
npm install @capacitor-community/storage-reactImport the hooks:
import { useStorage } from '@capacitor-community/storage-react'Then use the hooks in your app:
const [value, setValue] = useStorage('mykey');While Capacitor allows you to write to one API across several platforms, not all features are supported on all platforms. It is encouraged to check if the feature you intend to use is available before using it to avoid any runtime errors.
Each of the hook plugin paths exports an availableFeatures object, which contains a list features for that plugin. If the feature is supported for the current platform the app is running on, that feature will be true:
const { useStorageItem, availableFeatures } = `@capacitor-community/storage-react`;
const [value, setValue] = useStorage('mykey');
...
if(availableFeatures.useStorage) {
// Storage is available, feel free to use it!
setValue('cake');
}In Capacitor 3, all the plugins were separated into their own packages. Likewise, the new React hooks plugins were also put into their own package, so you will need to install the hook for each plugin you use.
Any deprecated API'S from Capacitor 2 to 3 were also removed and updated, so you might need to make some modifications to account for API changes. See the Capacitor Plugin API for to learn more.
Installation:
npm install @capacitor-community/app-reactUsage:
import { useAppState, useAppUrlOpen, useLaunchUrl, availableFeatures } from '@capacitor-community/app-react';useAppState provides access to App status information, such as whether the app is active or inactive. This value will update dynamically.
const {state} = useAppState();useLaunchUrl provides the URL the app was initially launched with. If you'd like to track future inbound URL events, use useAppUrlOpen below instead.
const { launchUrl } = useLaunchUrl();useAppUrlOpen provides the most recent URL used to activate the app. For example, if the user followed a link in another app that opened your app.
const { appUrlOpen } = useAppUrlOpen();See the App Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/browser-reactUsage:
import { useClose, useOpen, availableFeatures } from '@capacitor-community/browser-react';useOpen, useClose provides a way to launch, and close an in-app browser for external content:
// Open url in browser
const { open } = useOpen();
open({ url: 'http://ionicframework.com' });
// Close url in browser
const { close } = useClose();
useClose();See the Browser Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/camera-reactUsage:
import { useCamera, availableFeatures } from '@capacitor-community/camera-react';useCamera provides a way to take a photo:
const { photo, getPhoto } = useCamera();
const triggerCamera = useCallback(async () => {
getPhoto({
quality: 100,
allowEditing: false,
resultType: CameraResultType.DataUrl
})
}, [getPhoto]);
<div>{photo && <img alt="" src={photo.dataUrl} />}</div>See the Camera Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/clipboard-reactUsage:
import { useClipboard, availableFeatures } from '@capacitor-community/clipboard-react';useClipboard reads and writes clipboard data:
const { value, getValue, setValue } = useClipboard();
const paste = useCallback(async () => {
await setValue('http://ionicframework.com/);
}, [setValue]);
const copy = useCallback(async () => {
getValue();
}, [getValue])See the Clipboard Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/device-reactUsage:
import { useGetInfo, useGetLanguageCode, availableFeatures } from '@capacitor-community/device-react';useGetInfo, useGetLanguageCode gives access to device information and device language settings:
const { info } = useGetInfo();
const { languageCode } = useGetLanguageCode();See the Device Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/filesystem-reactUsage:
import { useFilesystem, base64FromPath, availableFeatures } from '@capacitor-community/filesystem-react';useFilesystem returns back common methods to gain access to file system apis.
const { readFile } = useFilesystem();
const file = await readFile({
path: filepath,
directory: FilesystemDirectory.Data
});base64FromPath is a helper method that will take in a path to a file and return back the base64 encoded representation of that file.
See the Filesystem Capacitor Plugin docs for more info on the plugin API.
const base64String = await base64FromPath(path);Installation:
npm install @capacitor-community/geolocation-reactUsage:
import { useCurrentPosition, useWatchPosition, availableFeatures } from '@capacitor-community/geolocation-react';useCurrentPosition returns a single geolocation position using the Geolocation API in Capacitor. The position can be manually updated by calling getPosition:
const { currentPosition, getPosition } = useCurrentPosition();
const handleRefreshPosition = () => {
getPosition();
}useWatchPosition tracks a geolocation position using the watchPosition in the Geolocation API in Capacitor. The location will automatically begin updating, and you can use the clearWatch and startWatch methods to manually stop and restart the watch.
const { currentPosition, startWatch, clearWatch } = useWatchPosition();See the Geolocation Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/keyboard-reactUsage:
import { useKeyboardState } from '@capacitor-community/keyboard';useKeyboard returns whether or not the on-screen keyboard is shown as well as an approximation of the keyboard height in pixels.
const { isOpen, keyboardHeight } = useKeyboard();
// Use keyboardHeight to translate an input that would otherwise be hidden by the keyboardSee the Keyboard Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/network-reactUsage:
import { useStatus, availableFeatures } from '@capacitor-community/network-react';useStatus monitors network status and information:
const { networkStatus } = useStatus();See the Network Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/screen-reader-reactUsage:
import { useIsScreenReaderEnabled, useSpeak, availableFeatures } from '@capacitor-community/screen-reader-react';useIsScreenReaderEnabled provides access to detecting and responding to a screen reading device or OS setting being enabled:
const {isScreenReaderEnabled} = useIsScreenReaderEnabled();useSpeak activates a text-to-speech engine (if available) to read spoken text.
const { speak } = useSpeak();
speak({value: textToSpeak})See the ScreenReader Capacitor Plugin docs for more info on the plugin API.
Installation:
npm install @capacitor-community/storage-reactUsage:
import { useStorage, useStorageItem, availableFeatures } from '@capacitor-community/storage-react';useStorage provides access to Capacitor's storage engine. There is also a helper called useStorageItem which makes managing a single item easy if you don't need to access the full Storage API (see below)
const { get, set, remove, getKeys, clear } = useStorage();
useEffect(() => {
async function example() {
const value = await get('name');
await set('name', 'Max');
await remove('name');
const allKeys = await getKeys();
await clear();
}
}, [ get, set, remove, keys, clear ]);useStorageItem tracks a single item and provides a nice way to read and write that item:
const [ name , setName ] = useStorageItem('name', 'Max');
// Example:
const updateName = useCallback((n) => {
setName(n);
}, [ setName ]);useStorageItem will use the initial value already in storage, or the one provided if there is no existing value.
See the Storage Capacitor Plugin docs for more info on the plugin API.
This is an evolving project and not all of the Capacitor Plugins are supported yet. If there is one you need, feel free top open an issue for it, or better yet, submit a PR!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent