@com-quicko/react-native-income-tax-sdk
v1.0.0
Published
Embedded Quicko income tax solution directly in your React Native app
Readme
@com-quicko/react-native-income-tax-sdk
A modern, high-performance React Native SDK that provides an embedded income tax filing solution directly in your mobile application. Seamlessly integrate Quicko's comprehensive tax services with minimal to zero external overhead.
Compatible with React Native CLI, Expo (Managed & Bare workflows), and React Native's New Architecture (Fabric).
Features
- 🎯 Embedded Tax Solution: Deliver Quicko's tax filing workflows natively inside your React Native app.
- ⚡ Zero Runtime Dependencies: The SDK runtime itself has 0 external dependencies—lightweight, secure, and immune to package conflicts.
- 🎨 Adaptive Theming: Automatic light and dark mode palette generation from any primary brand seed color with zero CSS or external theme libraries.
- 🔄 Real-Time Event Bridge: Bidirectional JavaScript bridge with real-time event notifications (
auth,filing,app_bar, and custom transactions). - 📱 Native Navigation & Gestures:
- Android hardware back button navigation with webview history support and smooth modal dismissal.
- Dynamic animated app bar that smoothly slides and collapses on webview visibility events.
- Automatic detection and completion handling for OAuth redirection (
oauth.quicko.com).
- 🛠️ Flexible Integration:
- React Hook:
useQuickoIncomeTax()for modern, functional components. - Declarative Modal:
<QuickoIncomeTaxModal />for straightforward state-driven UI. - Embedded View:
<QuickoIncomeTaxView />for custom screens in React Navigation or Expo Router. - Imperative Singleton:
QuickoSDK.instance.open()for programmatic triggering from service layers.
- React Hook:
Installation
# Using npm
npm install @com-quicko/react-native-income-tax-sdk react-native-webview
# Using yarn
yarn add @com-quicko/react-native-income-tax-sdk react-native-webview
# Using pnpm
pnpm add @com-quicko/react-native-income-tax-sdk react-native-webview
# Using Expo
npx expo install @com-quicko/react-native-income-tax-sdk react-native-webviewiOS CocoaPods Setup (Bare React Native only)
For React Native CLI projects on iOS, install the pods:
cd ios && pod install && cd ..(Expo projects do not require manual pod installation)
Usage
Approach 1: Context Provider & Hook (Recommended)
Wrap your app with <QuickoProvider> and trigger the SDK from any component using the useQuickoIncomeTax() hook:
1. Setup Provider in App Root (App.tsx or _layout.tsx)
import React from 'react';
import { QuickoProvider } from '@com-quicko/react-native-income-tax-sdk';
import HomeScreen from './HomeScreen';
export default function App() {
return (
<QuickoProvider
apiKey="key_your_api_key_here"
defaultOptions={{
intent: 'connect',
theme: {
mode: 'light',
seed: '#2962FF',
},
}}
onEvent={(event) => {
console.log('Global Tax Event:', event.type, event.data);
}}
>
<HomeScreen />
</QuickoProvider>
);
}2. Open SDK from Any Component
import React from 'react';
import { View, Button, StyleSheet } from 'react-native';
import { useQuickoIncomeTax } from '@com-quicko/react-native-income-tax-sdk';
export default function HomeScreen() {
const { open } = useQuickoIncomeTax();
const handleStartFiling = async () => {
try {
await open({
title: 'Income Tax 2026',
theme: {
mode: 'light',
seed: '#2962FF',
},
});
console.log('Tax workflow closed');
} catch (error) {
console.error('Failed to open tax SDK:', error);
}
};
return (
<View style={styles.container}>
<Button title="File Taxes Now" onPress={handleStartFiling} />
</View>
);
}
const styles = StyleSheet.create({
container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
});Approach 2: Declarative Modal (<QuickoIncomeTaxModal />)
If you prefer managing the modal visibility state explicitly:
import React, { useState } from 'react';
import { View, Button } from 'react-native';
import {
QuickoIncomeTaxModal,
type QuickoEvent,
} from '@com-quicko/react-native-income-tax-sdk';
export default function TaxScreen() {
const [isOpen, setIsOpen] = useState(false);
const handleEvent = (event: QuickoEvent) => {
console.log('Event received:', event.type, event.data);
};
return (
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Button title="Open Tax Center" onPress={() => setIsOpen(true)} />
<QuickoIncomeTaxModal
visible={isOpen}
apiKey="key_your_api_key_here"
onClose={() => setIsOpen(false)}
onEvent={handleEvent}
options={{
intent: 'connect',
title: 'Quicko Tax Center',
theme: {
mode: 'light',
seed: '#2962FF',
},
}}
/>
</View>
);
}Approach 3: Embedded View inside React Navigation / Expo Router
If you are using a dedicated screen in a Stack Navigator (React Navigation or Expo Router):
import React from 'react';
import {
QuickoIncomeTaxView,
type QuickoEvent,
} from '@com-quicko/react-native-income-tax-sdk';
import { useNavigation } from '@react-navigation/native';
export default function TaxFilingScreen() {
const navigation = useNavigation();
return (
<QuickoIncomeTaxView
apiKey="key_your_api_key_here"
onClose={() => navigation.goBack()}
onEvent={(event: QuickoEvent) => {
console.log('Event:', event);
}}
options={{
intent: 'connect',
title: 'Tax Filing',
theme: {
mode: 'light',
seed: '#00C853',
},
}}
/>
);
}Approach 4: Imperative Singleton
For developers preferring an imperative, service-driven pattern or invoking the SDK outside of standard React component trees:
import { QuickoSDK } from '@com-quicko/react-native-income-tax-sdk';
// 1. Set your API Key once during initialization
QuickoSDK.instance.setAPIKey('key_your_api_key_here');
// 2. Register event listener
QuickoSDK.instance.setEventListener({
onEvent(event) {
console.log('Quicko Event:', event);
},
});
// 3. Open the SDK UI (requires <QuickoProvider> in component tree)
await QuickoSDK.instance.open({
intent: 'connect',
title: 'Tax Center',
theme: {
mode: 'dark',
seed: '#2962FF',
},
});Configuration Options
The options object accepts configuration for routing, intent, and visual appearance:
const options: QuickoSDKOptions = {
intent: 'connect', // Required for API key authentication
title: 'Tax Center', // Header title (defaults to 'Tax Center')
theme: {
mode: 'light', // 'light' | 'dark'
seed: '#2962FF', // Primary brand color in hex format
colors: {
// Optional manual overrides
surface: '#FFFFFF',
onSurface: '#1C1B1F',
},
},
};Event Handling
The SDK communicates real-time progress and status back to your application:
interface QuickoEvent<T = unknown> {
type: string; // e.g. 'com.quicko.it.auth.success'
transactionId?: string;// Transaction ID associated with event
source?: string; // Source subsystem
success?: boolean; // Whether action succeeded
data?: T; // Payload data
}Common event patterns:
- Navigation / Header:
com.quicko.it.app_bar.showandcom.quicko.it.app_bar.hide(handled automatically by the SDK). - OAuth Authentication:
com.quicko.it.auth.successorcom.quicko.it.auth.failure. - Filing Progress:
com.quicko.it.filing.completed.
API Reference
QuickoSDK (Singleton)
| Method | Parameters | Returns | Description |
| :--- | :--- | :--- | :--- |
| setAPIKey | apiKey: string | void | Sets the API key. Throws if key does not start with "key_". |
| getAPIKey | - | string \| null | Returns the currently configured API key. |
| open | options?: QuickoSDKOptions | Promise<void> | Opens the SDK UI. Throws if API key not set when intent is 'connect'. |
| close | - | void | Closes active SDK modal. |
| setEventListener | listener: QuickoEventListener \| Callback | void | Registers a listener to receive SDK events. |
| getOptions | - | QuickoSDKOptions | Returns current options copy. |
| getTheme | - | { mode, seed } | Returns resolved theme mode and seed color. |
| getColorScheme | - | QuickoColorScheme | Computes full Material-based color scheme. |
| reset | - | void | Resets singleton state (useful for tests). |
<QuickoIncomeTaxModal /> Props
Inherits all props from QuickoIncomeTaxViewProps plus:
| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| visible | boolean | Required | Controls visibility of the modal. |
| animationType | 'slide' \| 'fade' \| 'none' | 'slide' | Modal transition animation. |
| onClose | () => void | Required | Invoked when modal is closed. |
<QuickoIncomeTaxView /> Props
| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| options | QuickoSDKOptions | {} | Options for route, intent, and theming. |
| apiKey | string | SDK Key | Overrides QuickoSDK.instance.getAPIKey(). |
| onClose | () => void | undefined | Callback invoked on close button tap or OAuth return. |
| onEvent | (event: QuickoEvent) => void | undefined | Callback for SDK events. |
| showAppBar | boolean | true | Initial visibility of animated header. |
| style | StyleProp<ViewStyle> | undefined | Root view styling. |
| renderCloseIcon | () => ReactNode | undefined | Custom close button icon renderer. |
| renderHeader | (props) => ReactNode | undefined | Completely replace the header bar with a custom component. |
| renderLoading | () => ReactNode | Spinner | Custom loading component while web view loads. |
| renderError | (error) => ReactNode | undefined | Custom error screen renderer. |
| WebViewComponent | ComponentType<any> | Auto | Custom or mocked WebView component. |
| webViewProps | Record<string, unknown> | {} | Pass-through props forwarded to underlying WebView. |
Requirements
- React Native:
>= 0.70.0 - React:
>= 18.0.0 - react-native-webview:
>= 13.0.0 - Android: API 21+
- iOS: iOS 13.0+
Support & Resources
- Website: https://quicko.com/connect
- Developer Documentation: Check the Quicko developer portal for detailed integration guides.
- Support: Contact
[email protected]for technical assistance and API keys.
License
Proprietary and Confidential. Copyright © 2026 Quicko Infosoft Private Limited. All Rights Reserved.
Use of this SDK is subject to the terms and conditions of your commercial agreement or partner license with Quicko Infosoft Private Limited. See the LICENSE file for complete terms.
