--- description: Capacitor plugin for running background tasks. It allows apps to execute tasks when moved to the background. title: Capacitor Background Task Plugin for iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/background-task.png --- [Skip to content ](#capacitor-background-task-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Type Aliases ](#type-aliases) * [ Quirks ](#quirks) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Credits ](#credits) * [ Badge ](/docs/sdks/capacitor/badge/) * [ Barometer ](/docs/sdks/capacitor/barometer/) * [ Battery ](/docs/sdks/capacitor/battery/) * [ Biometrics ](/docs/sdks/capacitor/biometrics/) * [ Bluetooth Low Energy ](/docs/sdks/capacitor/bluetooth-low-energy/) * [ Clipboard ](/docs/sdks/capacitor/clipboard/) * [ Cloudinary ](/docs/sdks/capacitor/cloudinary/) * [ Compass ](/docs/sdks/capacitor/compass/) * [ Contacts ](/docs/sdks/capacitor/contacts/) * [ Crisp ](/docs/sdks/capacitor/crisp/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Electron ](/docs/sdks/capacitor/electron/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Type Aliases ](#type-aliases) * [ Quirks ](#quirks) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Credits ](#credits) # Capacitor Background Task Plugin[ΒΆ](#capacitor-background-task-plugin "Permanent link") Capacitor plugin for running background tasks. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Use Cases[ΒΆ](#use-cases "Permanent link") The Background Task plugin is typically used to finish short-running work when the app moves to the background, for example: * **Finish network requests**: Complete an upload or API request that was started while the app was in the foreground. * **Save application state**: Persist unsaved user input or app state before the OS puts the app to sleep. * **Sync data**: Finish writing pending changes to your backend or local storage. * **Clean up resources**: Close connections or release resources gracefully before the app is suspended. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | \>=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | | 6.x.x | 6.x.x | Deprecated | | 5.x.x | 5.x.x | Deprecated | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-background-task` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-background-task [](#%5F%5Fcodelineno-2-2)npx cap sync ` ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Demo[ΒΆ](#demo "Permanent link") A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo) ## Usage[ΒΆ](#usage "Permanent link") `` [](#%5F%5Fcodelineno-3-1)import { App } from '@capacitor/app'; [](#%5F%5Fcodelineno-3-2)import { BackgroundTask } from '@capawesome/capacitor-background-task'; [](#%5F%5Fcodelineno-3-3) [](#%5F%5Fcodelineno-3-4)App.addListener('appStateChange', async ({ isActive }) => { [](#%5F%5Fcodelineno-3-5) if (isActive) { [](#%5F%5Fcodelineno-3-6) return; [](#%5F%5Fcodelineno-3-7) } [](#%5F%5Fcodelineno-3-8) // The app state has been changed to inactive. [](#%5F%5Fcodelineno-3-9) // Start the background task by calling `beforeExit`. [](#%5F%5Fcodelineno-3-10) const taskId = await BackgroundTask.beforeExit(async () => { [](#%5F%5Fcodelineno-3-11) // Run your code... [](#%5F%5Fcodelineno-3-12) // Finish the background task as soon as everything is done. [](#%5F%5Fcodelineno-3-13) BackgroundTask.finish({ taskId }); [](#%5F%5Fcodelineno-3-14) }); [](#%5F%5Fcodelineno-3-15)}); `` ## API[ΒΆ](#api "Permanent link") * [beforeExit(...)](#beforeexit) * [finish(...)](#finish) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### beforeExit(...)[ΒΆ](#beforeexit "Permanent link") `[](#%5F%5Fcodelineno-4-1)beforeExit(cb: () => void) => Promise ` Call this method when the app moves to the background. It allows the app to continue running a task in the background. On **iOS** this method should be finished in less than 30 seconds. Only available on Android and iOS. | Param | Type | | ------ | ---------- | | **cb** | () => void | **Returns:** `Promise` --- ### finish(...)[ΒΆ](#finish "Permanent link") `[](#%5F%5Fcodelineno-5-1)finish(options: FinishOptions) => void ` Finish the current background task. The OS will put the app to sleep. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------- | | **options** | [FinishOptions](#finishoptions) | --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### FinishOptions[ΒΆ](#finishoptions "Permanent link") | Prop | Type | | ---------- | ------------------------- | | **taskId** | [CallbackID](#callbackid) | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### CallbackID[ΒΆ](#callbackid "Permanent link") `string` ## Quirks[ΒΆ](#quirks "Permanent link") ### iOS[ΒΆ](#ios "Permanent link") On **iOS** the [UIKit framework](https://developer.apple.com/documentation/uikit) is used. Read more about the implementation and any limitations [here](https://developer.apple.com/documentation/uikit/app%5Fand%5Fenvironment/scenes/preparing%5Fyour%5Fui%5Fto%5Frun%5Fin%5Fthe%5Fbackground/extending%5Fyour%5Fapp%5Fs%5Fbackground%5Fexecution%5Ftime). ### Android[ΒΆ](#android "Permanent link") There is currently no ready implementation on **Android**. It's planned to add the support in the near future. ## FAQ[ΒΆ](#faq "Permanent link") ### How much time does my task have to run in the background?[ΒΆ](#how-much-time-does-my-task-have-to-run-in-the-background "Permanent link") On iOS, the task started with `beforeExit(...)` should be finished in less than 30 seconds. As soon as your work is done, call `finish(...)` so the OS can put the app to sleep. Read more about the underlying background execution mechanism in the [Apple documentation](https://developer.apple.com/documentation/uikit/app%5Fand%5Fenvironment/scenes/preparing%5Fyour%5Fui%5Fto%5Frun%5Fin%5Fthe%5Fbackground/extending%5Fyour%5Fapp%5Fs%5Fbackground%5Fexecution%5Ftime). ### Is this plugin supported on Android?[ΒΆ](#is-this-plugin-supported-on-android "Permanent link") There is currently no ready implementation on Android, so the task is not extended there. Support for Android is planned for the future, see the [Quirks](#quirks) section. ### Can I run periodic or scheduled tasks with this plugin?[ΒΆ](#can-i-run-periodic-or-scheduled-tasks-with-this-plugin "Permanent link") No, this plugin is designed to extend the execution time of your app when it moves to the background, so you can finish a short-running task. It does not schedule tasks that run while the app is closed. ### How do I know when the app moves to the background?[ΒΆ](#how-do-i-know-when-the-app-moves-to-the-background "Permanent link") Use the `appStateChange` listener of the official `@capacitor/app` plugin, as shown in the [Usage](#usage) section. When `isActive` becomes `false`, call `beforeExit(...)` to start the background task. ### When do I have to call the `finish` method?[ΒΆ](#when-do-i-have-to-call-the-finish-method "Permanent link") Call `finish(...)` with the task ID returned by `beforeExit(...)` as soon as everything is done. This tells the OS that the task is complete so it can put the app to sleep. ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Run a foreground service on Android for long-running work. * [Alarm](https://capawesome.io/docs/sdks/capacitor/alarm/): Create system alarms and timers. * [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake while your app is in the foreground. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-task/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/background-task/LICENSE). ## Credits[ΒΆ](#credits "Permanent link") This plugin is based on the [Capacitor Background Task](https://github.com/capawesome-team/capacitor-background-task) plugin. Thanks to everyone who contributed to the project! July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/background-task/#article", "headline": "Capacitor Background Task Plugin for iOS", "name": "Capacitor Background Task Plugin for iOS", "description": "Capacitor plugin for running background tasks. It allows apps to execute tasks when moved to the background.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/background-task/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/background-task/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/background-task/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/background-task/#software", "name": "Capacitor Background Task Plugin for iOS", "description": "Capacitor plugin for running background tasks. It allows apps to execute tasks when moved to the background.", "url": "https://capawesome.io/docs/sdks/capacitor/background-task/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How much time does my task have to run in the background?", "acceptedAnswer": {"@type": "Answer", "text": "On iOS, the task started with beforeExit(...) should be finished in less than 30 seconds. As soon as your work is done, call finish(...) so the OS can put the app to sleep. Read more about the underlying background execution mechanism in the Apple documentation."}}, {"@type": "Question", "name": "Is this plugin supported on Android?", "acceptedAnswer": {"@type": "Answer", "text": "There is currently no ready implementation on Android, so the task is not extended there. Support for Android is planned for the future, see the Quirks section."}}, {"@type": "Question", "name": "Can I run periodic or scheduled tasks with this plugin?", "acceptedAnswer": {"@type": "Answer", "text": "No, this plugin is designed to extend the execution time of your app when it moves to the background, so you can finish a short-running task. It does not schedule tasks that run while the app is closed."}}, {"@type": "Question", "name": "How do I know when the app moves to the background?", "acceptedAnswer": {"@type": "Answer", "text": "Use the appStateChange listener of the official @capacitor/app plugin, as shown in the Usage section. When isActive becomes false, call beforeExit(...) to start the background task."}}, {"@type": "Question", "name": "When do I have to call the finish method?", "acceptedAnswer": {"@type": "Answer", "text": "Call finish(...) with the task ID returned by beforeExit(...) as soon as everything is done. This tells the OS that the task is complete so it can put the app to sleep."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/background-task/"} ```