React Native Today Widget
Experimental library investigating limits of implementation iOS App Extensions using React Native.
Sample result from Complex example:
What is Today Widget?
Getting started
This library will help you to add iOS Today Widget App Extension without need to open XCode.
Dependencies
xcodeprojfor linking script:
$ gem install xcodeproj
You may need to use sudo gem install xcodeproj or sudo gem install -n /usr/local/bin xcodeproj depends on your Ruby installation.
- For React Native compatibility, check peerDependencies in package.json
Setup
$ yarn add react-native-today-widget
$ react-native link
You could use $ npm i react-native-today-widget --save as well, but don't forget to save it in package.json dependencies. Otherwise RN will not link it.
Whenever you change Bundle Identifier (CFBundleIdentifier) for main app, you have to run
./node_modules/.bin/bundle-idscript or reinstall the module (rm -rf node_modules/react-native-today-widget && yarn)
Manual linking
react-native link should works, but in case of some troubles, you could follow general guide for linking libraries.
- file for Step 1 is
/node_modules/react-native-today-widget/ios/RNTodayWidgetExtension.xcodeproj - as a Step 2, add
TodayWidgetExtension.appexto Embedded Binaries on the General tab for your main target - in Step 3, add
$(SRCROOT)/../node_modules/react-native-today-widget/ios/TodayWidgetExtensionto Header Search Paths
Usage
All you need is to create an index.widget.js file at the root and register there your component for key TodayWidgetExtension:
const TodayWidget = () => (
<View>
<Text>
Hello Today Widget!
</Text>
</View>
);
AppRegistry.registerComponent('TodayWidgetExtension', () => TodayWidget);
Please note that registering both the widget and the main app in
index.jsfile can cause memory issues. Because the app is also bundled (even if you don't use it in your widget), and it causes 'Unable to load' error. When we split the registration into two different files, the widget and the main app are bundled seperately. See blog post from Maxim Toyberman.
In place of TodayWidget component, you could use any JSX component. See Basic example.
Run your app as usual:
react-native run-ios
Display new widget on Search screen or by force touch on your app icon (on devices supporting 3D Touch).
If you need to see logs from TodayWidgetExtension, use:
react-native log-ios
In your extension scheme’s Run phase, you specify a
host appas the executable
Memory limitation
The memory limit for Today Widget on device is 16 MB. (Great explanation is in this talk by Conrad Kramer)
Verified experimentally using XCode debugger - while loading big image, Today Widget crashes as soon as it reaches 16 MB memory usage.
Memory usage of Basic example with just one Text element is about 11 MB. Up to 13 MB during content rendering.
For running Today Widget on device you have to use
Releasebuild configuration. Development mode adds too much overhead. Only possibility to run the widget on device in development mode is using Instruments tool to temporarily disable the limit.
Notes
- Every native change on widget project is only in
node_modulesso probably gitignored! - For recommended transparent background simply don't set any
backgroundColorfor your Today Widget component. - Human Interface Guidelines
- More about: iOS App Extensions
- Today Widget in App Extension Programming Guide
To investigate more iOS App Extensions with React Native check those:
- react-native-share-extension
- react-native-share-menu
- Messages App/App Extension (iOS10) with React Native
API Reference
DevMenu
Default dev menu is not available in widget, but you could use DevSettings from NativeModules or this prepared DevMenu component to enable Live/Hot reload or remote JS debugging.
children- trigger element (TouchableOpacity by default)style- overriding default style for trigger elementtitle- set trigger text ('DM' by default)
Example
import { DevMenu } from 'react-native-today-widget';
const TodayWidget = () => (
<View>
<Text>Hello Today Widget!</Text>
{__DEV__ && <DevMenu />
/* Has to be a last element to be clickable,
because it has absolute position */
}
</View>
);
Screenshot of opened Developer Menu:
openURL([url:string])
Asks the system open a URL on behalf of the currently running app extension.
url- the URL to open
If you employ this method to open other apps from your widget, your App Store submission might entail additional review to ensure compliance with the intent of widgets.
setExpandable([expandable:boolean = true], [maxHeight:number = 110])
Enables to display native Show More / Less button in top right corner of the widget (iOS 10).
expandable- iffalseShow More / Less button is hiddenmaxHeight- height of expanded widget
Height of collapsed Today Widget is always 110px on iOS 10.
Example
import { setExpandable } from 'react-native-today-widget';
const TodayWidget = () => {
const isExpandable = true;
const maxHeight = 500;
setExpandable(isExpandable, maxHeight);
const onLayout = (event) => {
const height = event.nativeEvent.layout.height;
if (height <= 110) {
console.log('widget is in compact mode');
}
else if (height > 110) {
console.log('widget is in expanded mode');
}
}
return (
<View onLayout={onLayout}>
<Text>
Hello Today Widget!
</Text>
</View>
);
};
You could try Expandable example
![[error] react-native link Package name not found in {app-folder}/android/app/src/debug/AndroidManifest.xml](https://avatars.githubusercontent.com/u/1158435?v=4)
18.8k Jan 4, 2023
2.9k Jan 9, 2023
153 Oct 23, 2022
272 Dec 9, 2022
222 Dec 26, 2022
24 Feb 14, 2022
23.1k Dec 31, 2022
4.8k Jan 5, 2023
258 Dec 16, 2022
106 Nov 10, 2022
63 Feb 14, 2022
20.4k Jan 3, 2023
15.2k Jan 5, 2023
158 Dec 16, 2022
374 Dec 30, 2022
1.4k Dec 26, 2022
117 Dec 19, 2022