); } export function Main() { const db = useSQLiteContext(); console.log('sqlite version', db.getFirstSync('SELECT sqlite_version()')); return } ``` ## Classes ### `SQLiteDatabase` Supported platforms: Android, iOS, macOS, tvOS, Web. A SQLite database. SQLiteDatabase Properties ### `databasePath` Supported platforms: Android, iOS, macOS, tvOS, Web. Read Only • Type: `string` ### `nativeDatabase` Supported platforms: Android, iOS, macOS, tvOS, Web. Read Only • Type: [NativeDatabase](#nativedatabase) ### `options` Supported platforms: Android, iOS, macOS, tvOS, Web. Read Only • Type: [SQLiteOpenOptions](#sqliteopenoptions) SQLiteDatabase Methods ### `closeAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Close the database. Returns: `Promise` ### `closeSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Close the database. Returns: `void` ### `createSessionAsync(dbName)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `dbName`(optional) | `string` | The name of the database to create a session for. The default value is `main`. Default: `'main'` | Create a new session for the database. Returns: `Promise` > **See:** [`sqlite3session_create`](https://www.sqlite.org/session/sqlite3session_create.html) ### `createSessionSync(dbName)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `dbName`(optional) | `string` | The name of the database to create a session for. The default value is `main`. Default: `'main'` | Create a new session for the database. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteSession` > **See:** [`sqlite3session_create`](https://www.sqlite.org/session/sqlite3session_create.html) ### `execAsync(source)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing all the SQL queries. | Execute all SQL queries in the supplied string. > Note: The queries are not escaped for you! Be careful when constructing your queries. Returns: `Promise` ### `execSync(source)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing all the SQL queries. | Execute all SQL queries in the supplied string. > **Note:** The queries are not escaped for you! Be careful when constructing your queries. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` ### `getAllAsync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareAsync()`](#prepareasyncsource), [`SQLiteStatement.executeAsync()`](#executeasyncparams), [`SQLiteExecuteAsyncResult.getAllAsync()`](#getallasync), and [`SQLiteStatement.finalizeAsync()`](#finalizeasync). Returns: `Promise` Example ```ts // For unnamed parameters, you pass values in an array. db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', [1, 'Hello']); // For unnamed parameters, you pass values in variadic arguments. db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', 1, 'Hello'); // For named parameters, you should pass values in object. db.getAllAsync('SELECT * FROM test WHERE intValue = $intValue AND name = $name', { $intValue: 1, $name: 'Hello' }); ``` ### `getAllSync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareSync()`](#preparesyncsource), [`SQLiteStatement.executeSync()`](#executesyncparams), [`SQLiteExecuteSyncResult.getAllSync()`](#getallsync), and [`SQLiteStatement.finalizeSync()`](#finalizesync). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `T[]` ### `getEachAsync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareAsync()`](#prepareasyncsource), [`SQLiteStatement.executeAsync()`](#executeasyncparams), [`SQLiteExecuteAsyncResult`](#sqliteexecuteasyncresult) `AsyncIterator`, and [`SQLiteStatement.finalizeAsync()`](#finalizeasync). Returns: `AsyncIterableIterator` Rather than returning Promise, this function returns an [`AsyncIterableIterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator). You can use `for await...of` to iterate over the rows from the SQLite query result. ### `getEachSync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareSync()`](#preparesyncsource), [`SQLiteStatement.executeSync()`](#executesyncparams), [`SQLiteExecuteSyncResult`](#sqliteexecutesyncresult) `Iterator`, and [`SQLiteStatement.finalizeSync()`](#finalizesync). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `IterableIterator` This function returns an [`IterableIterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator). You can use `for...of` to iterate over the rows from the SQLite query result. ### `getFirstAsync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareAsync()`](#prepareasyncsource), [`SQLiteStatement.executeAsync()`](#executeasyncparams), [`SQLiteExecuteAsyncResult.getFirstAsync()`](#getfirstasync), and [`SQLiteStatement.finalizeAsync()`](#finalizeasync). Returns: `Promise` ### `getFirstSync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareSync()`](#preparesyncsource), [`SQLiteStatement.executeSync()`](#executesyncparams), [`SQLiteExecuteSyncResult.getFirstSync()`](#getfirstsync), and [`SQLiteStatement.finalizeSync()`](#finalizesync). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `T | null` ### `isInTransactionAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Asynchronous call to return whether the database is currently in a transaction. Returns: `Promise` ### `isInTransactionSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Synchronous call to return whether the database is currently in a transaction. Returns: `boolean` ### `loadExtensionAsync(libPath, entryPoint)` Supported platforms: Android, iOS, macOS, tvOS. | Parameter | Type | Description | | --- | --- | --- | | `libPath` | `string` | The path to the extension library file. | | `entryPoint`(optional) | `string` | The entry point of the extension. If not provided, the default entry point is inferred by [`sqlite3_load_extension`](https://www.sqlite.org/c3ref/load_extension.html). | Load a SQLite extension. Returns: `Promise` Example ```ts // Load `sqlite-vec` from `bundledExtensions`. You need to enable `withSQLiteVecExtension` to include `sqlite-vec`. const extension = SQLite.bundledExtensions['sqlite-vec']; await db.loadExtensionAsync(extension.libPath, extension.entryPoint); // You can also load a custom extension. await db.loadExtensionAsync('/path/to/extension'); ``` ### `loadExtensionSync(libPath, entryPoint)` Supported platforms: Android, iOS, macOS, tvOS. | Parameter | Type | Description | | --- | --- | --- | | `libPath` | `string` | The path to the extension library file. | | `entryPoint`(optional) | `string` | The entry point of the extension. If not provided, the default entry point is inferred by [`sqlite3_load_extension`](https://www.sqlite.org/c3ref/load_extension.html). | Load a SQLite extension. Returns: `void` Example ```ts // Load `sqlite-vec` from `bundledExtensions`. You need to enable `withSQLiteVecExtension` to include `sqlite-vec`. const extension = SQLite.bundledExtensions['sqlite-vec']; db.loadExtensionSync(extension.libPath, extension.entryPoint); // You can also load a custom extension. db.loadExtensionSync('/path/to/extension'); ``` ### `prepareAsync(source)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | Create a [prepared SQLite statement](https://www.sqlite.org/c3ref/prepare.html). Returns: `Promise` ### `prepareSync(source)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | Create a [prepared SQLite statement](https://www.sqlite.org/c3ref/prepare.html). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteStatement` ### `runAsync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareAsync()`](#prepareasyncsource), [`SQLiteStatement.executeAsync()`](#executeasyncparams), and [`SQLiteStatement.finalizeAsync()`](#finalizeasync). Returns: `Promise` ### `runSync(source, params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `source` | `string` | A string containing the SQL query. | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | A convenience wrapper around [`SQLiteDatabase.prepareSync()`](#preparesyncsource), [`SQLiteStatement.executeSync()`](#executesyncparams), and [`SQLiteStatement.finalizeSync()`](#finalizesync). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteRunResult` ### `serializeAsync(databaseName)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `databaseName`(optional) | `string` | The name of the current attached databases. The default value is `main` which is the default database name. Default: `'main'` | [Serialize the database](https://sqlite.org/c3ref/serialize.html) as `Uint8Array`. Returns: `Promise **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `Uint8Array` ### `sql(strings, ...values)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `strings` | [TemplateStringsArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TemplateStringsArray) | | `. .values` | `unknown[]` | Execute SQL queries using tagged template literals (Bun-style API). Queries are automatically protected against SQL injection using prepared statements. The query result is directly awaitable and returns an array of objects by default. Use `.values()`, `.first()`, or `.each()` for different result formats. Returns: `SQLiteTaggedQuery` Example ```ts // Direct await - returns array of objects const users = await sql`SELECT * FROM users WHERE age > ${21}`; // Get first row only const user = await sql`SELECT * FROM users WHERE id = ${userId}`.first(); // Get values as arrays const rows = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]] // INSERT/UPDATE/DELETE - returns SQLiteRunResult const result = await sql`INSERT INTO users (name, age) VALUES (${name}, ${age})` as SQLiteRunResult; console.log('Inserted row:', result.lastInsertRowId); // Iteration for await (const user of db`SELECT * FROM users`.each()) { console.log(user.name); } // Synchronous API const users = sql`SELECT * FROM users WHERE age > ${21}`.allSync(); const user = sql`SELECT * FROM users WHERE id = ${userId}`.firstSync(); ``` ### `syncLibSQL()` Supported platforms: Android, iOS, macOS, tvOS, Web. Synchronize the local database with the remote libSQL server. This method is only available from libSQL integration. Returns: `Promise` ### `withExclusiveTransactionAsync(task)` Supported platforms: Android, iOS, macOS, tvOS. | Parameter | Type | Description | | --- | --- | --- | | `task` | (txn: Transaction) => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | An async function to execute within a transaction. Any queries inside the transaction must be executed on the `txn` object. The `txn` object has the same interfaces as the [`SQLiteDatabase`](#sqlitedatabase) object. You can use `txn` like a [`SQLiteDatabase`](#sqlitedatabase) object. | Execute a transaction and automatically commit/rollback based on the `task` result. The transaction may be exclusive. As long as the transaction is converted into a write transaction, the other async write queries will abort with `database is locked` error. > **Note:** This function is not supported on web. Returns: `Promise` Example ```ts db.withExclusiveTransactionAsync(async (txn) => { await txn.execAsync('UPDATE test SET name = "aaa"'); }); ``` ### `withTransactionAsync(task)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `task` | () => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | An async function to execute within a transaction. | Execute a transaction and automatically commit/rollback based on the `task` result. > **Note:** This transaction is not exclusive and can be interrupted by other async queries. Returns: `Promise` Example ```ts db.withTransactionAsync(async () => { await db.execAsync('UPDATE test SET name = "aaa"'); // // We cannot control the order of async/await order, so order of execution is not guaranteed. // The following UPDATE query out of transaction may be executed here and break the expectation. // const result = await db.getFirstAsync<{ name: string }>('SELECT name FROM Users'); expect(result?.name).toBe('aaa'); }); db.execAsync('UPDATE test SET name = "bbb"'); ``` If you worry about the order of execution, use `withExclusiveTransactionAsync` instead. ### `withTransactionSync(task)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `task` | `() => void` | An async function to execute within a transaction. | Execute a transaction and automatically commit/rollback based on the `task` result. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` ### `SQLiteSession` Supported platforms: Android, iOS, macOS, tvOS, Web. A class that represents an instance of the SQLite session extension. > **See:** [Session Extension](https://www.sqlite.org/sessionintro.html) SQLiteSession Methods ### `applyChangesetAsync(changeset)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `changeset` | [Changeset](#changeset) | The changeset to apply. | Apply a changeset asynchronously. Returns: `Promise` > **See:** [`sqlite3changeset_apply`](https://www.sqlite.org/session/sqlite3changeset_apply.html) ### `applyChangesetSync(changeset)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `changeset` | [Changeset](#changeset) | The changeset to apply. | Apply a changeset synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` > **See:** [`sqlite3changeset_apply`](https://www.sqlite.org/session/sqlite3changeset_apply.html) ### `attachAsync(table)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `table` | `string | null` | The table to attach. If `null`, all tables are attached. | Attach a table to the session asynchronously. Returns: `Promise` > **See:** [`sqlite3session_attach`](https://www.sqlite.org/session/sqlite3session_attach.html) ### `attachSync(table)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `table` | `string | null` | The table to attach. | Attach a table to the session synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` > **See:** [`sqlite3session_attach`](https://www.sqlite.org/session/sqlite3session_attach.html) ### `closeAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Close the session asynchronously. Returns: `Promise` > **See:** [`sqlite3session_delete`](https://www.sqlite.org/session/sqlite3session_delete.html) ### `closeSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Close the session synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` > **See:** [`sqlite3session_delete`](https://www.sqlite.org/session/sqlite3session_delete.html) ### `createChangesetAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Create a changeset asynchronously. Returns: `Promise` > **See:** [`sqlite3session_changeset`](https://www.sqlite.org/session/sqlite3session_changeset.html) ### `createChangesetSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Create a changeset synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `Changeset` > **See:** [`sqlite3session_changeset`](https://www.sqlite.org/session/sqlite3session_changeset.html) ### `createInvertedChangesetAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Create an inverted changeset asynchronously. This is a shorthand for [`createChangesetAsync()`](#createchangesetasync) + [`invertChangesetAsync()`](#invertchangesetasyncchangeset). Returns: `Promise` ### `createInvertedChangesetSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Create an inverted changeset synchronously. This is a shorthand for [`createChangesetSync()`](#createchangesetsync) + [`invertChangesetSync()`](#invertchangesetsyncchangeset). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `Changeset` ### `enableAsync(enabled)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `enabled` | `boolean` | Whether to enable or disable the session. | Enable or disable the session asynchronously. Returns: `Promise` > **See:** [`sqlite3session_enable`](https://www.sqlite.org/session/sqlite3session_enable.html) ### `enableSync(enabled)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `enabled` | `boolean` | Whether to enable or disable the session. | Enable or disable the session synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` > **See:** [`sqlite3session_enable`](https://www.sqlite.org/session/sqlite3session_enable.html) ### `invertChangesetAsync(changeset)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `changeset` | [Changeset](#changeset) | The changeset to invert. | Invert a changeset asynchronously. Returns: `Promise` > **See:** [`sqlite3changeset_invert`](https://www.sqlite.org/session/sqlite3changeset_invert.html) ### `invertChangesetSync(changeset)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `changeset` | [Changeset](#changeset) | The changeset to invert. | Invert a changeset synchronously. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `Changeset` > **See:** [`sqlite3changeset_invert`](https://www.sqlite.org/session/sqlite3changeset_invert.html) ### `SQLiteStatement` Supported platforms: Android, iOS, macOS, tvOS, Web. A prepared statement returned by [`SQLiteDatabase.prepareAsync()`](#prepareasyncsource) or [`SQLiteDatabase.prepareSync()`](#preparesyncsource) that can be binded with parameters and executed. SQLiteStatement Methods ### `executeAsync(params)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `params` | [SQLiteBindParams](#sqlitebindparams) | The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`SQLiteBindValue`](#sqlitebindvalue) for more information about binding values. | Run the prepared statement and return the [`SQLiteExecuteAsyncResult`](#sqliteexecuteasyncresult) instance. Returns: `Promise **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteExecuteSyncResult` ### `finalizeAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Finalize the prepared statement. This will call the [`sqlite3_finalize()`](https://www.sqlite.org/c3ref/finalize.html) C function under the hood. Attempting to access a finalized statement will result in an error. > **Note:** While `expo-sqlite` will automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use the `try...finally` statement to ensure that prepared statements are finalized even if an error occurs. Returns: `Promise` ### `finalizeSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Finalize the prepared statement. This will call the [`sqlite3_finalize()`](https://www.sqlite.org/c3ref/finalize.html) C function under the hood. Attempting to access a finalized statement will result in an error. > **Note:** While `expo-sqlite` will automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use the `try...finally` statement to ensure that prepared statements are finalized even if an error occurs. Returns: `void` ### `getColumnNamesAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get the column names of the prepared statement. Returns: `Promise` ### `getColumnNamesSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get the column names of the prepared statement. Returns: `string[]` ### `SQLiteStorage` Supported platforms: Android, iOS, macOS, tvOS, Web. Key-value store backed by SQLite. This class accepts a `databaseName` parameter in its constructor, which is the name of the database file to use for the storage. SQLiteStorage Methods ### `clear()` Supported platforms: Android, iOS, macOS, tvOS, Web. Alias for [`clearAsync()`](#clearasync) method. Returns: `Promise` ### `clearAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Clears all key-value pairs from the storage asynchronously. Returns: `Promise` ### `clearSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Clears all key-value pairs from the storage synchronously. Returns: `boolean` ### `close()` Supported platforms: Android, iOS, macOS, tvOS, Web. Alias for [`closeAsync()`](#closeasync-1) method. Returns: `Promise` ### `closeAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Closes the database connection asynchronously. Returns: `Promise` ### `closeSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Closes the database connection synchronously. Returns: `void` ### `getAllKeys()` Supported platforms: Android, iOS, macOS, tvOS, Web. Alias for [`getAllKeysAsync()`](#getallkeysasync) method. Returns: `Promise` ### `getAllKeysAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Retrieves all keys stored in the storage asynchronously. Returns: `Promise` ### `getAllKeysSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Retrieves all keys stored in the storage synchronously. Returns: `string[]` ### `getItem(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Alias for [`getItemAsync()`](#getitemasynckey) method. Returns: `Promise` ### `getItemAsync(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Retrieves the value associated with the given key asynchronously. Returns: `Promise` ### `getItemSync(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Retrieves the value associated with the given key synchronously. Returns: `string | null` ### `getKeyByIndexAsync(index)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `index` | `number` | Retrieves the key at the given index asynchronously. Returns: `Promise` ### `getKeyByIndexSync(index)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `index` | `number` | Retrieves the key at the given index synchronously. Returns: `string | null` ### `getLengthAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Retrieves the number of key-value pairs stored in the storage asynchronously. Returns: `Promise` ### `getLengthSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Retrieves the number of key-value pairs stored in the storage synchronously. Returns: `number` ### `mergeItem(key, value)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | | `value` | `string` | Merges the given value with the existing value for the given key asynchronously. If the existing value is a JSON object, performs a deep merge. Returns: `Promise` ### `multiGet(keys)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `keys` | `string[]` | Retrieves the values associated with the given keys asynchronously. Returns: `Promise` ### `multiMerge(keyValuePairs)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `keyValuePairs` | `undefined` | Merges multiple key-value pairs asynchronously. If existing values are JSON objects, performs a deep merge. Returns: `Promise` ### `multiRemove(keys)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `keys` | `string[]` | Removes the values associated with the given keys asynchronously. Returns: `Promise` ### `multiSet(keyValuePairs)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `keyValuePairs` | `undefined` | Sets multiple key-value pairs asynchronously. Returns: `Promise` ### `removeItem(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Alias for [`removeItemAsync()`](#removeitemasynckey) method. Returns: `Promise` ### `removeItemAsync(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Removes the value associated with the given key asynchronously. Returns: `Promise` ### `removeItemSync(key)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | Removes the value associated with the given key synchronously. Returns: `boolean` ### `setItem(key, value)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | | `value` | string | [SQLiteStorageSetItemUpdateFunction](/versions/latest/sdk/sqlite#sqlitestoragesetitemupdatefunctionprevvalue) | Alias for [`setItemAsync()`](#setitemasynckey-value). Returns: `Promise` ### `setItemAsync(key, value)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | | `value` | string | [SQLiteStorageSetItemUpdateFunction](/versions/latest/sdk/sqlite#sqlitestoragesetitemupdatefunctionprevvalue) | Sets the value for the given key asynchronously. If a function is provided, it computes the new value based on the previous value. Returns: `Promise` ### `setItemSync(key, value)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `key` | `string` | | `value` | string | [SQLiteStorageSetItemUpdateFunction](/versions/latest/sdk/sqlite#sqlitestoragesetitemupdatefunctionprevvalue) | Sets the value for the given key synchronously. If a function is provided, it computes the new value based on the previous value. Returns: `void` ### `SQLiteTaggedQuery` Supported platforms: Android, iOS, macOS, tvOS, Web. Type: Class implements [PromiseLike](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\> A SQL query with tagged template literals API that can be awaited directly (returns array of objects by default), or transformed using .values() or .first() methods. This API is inspired by Bun's SQL interface: Example ```ts // Default: returns array of objects const users = await sql`SELECT * FROM users WHERE age > ${21}`; // Get values as arrays const values = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]] // Get first row only const user = await sql`SELECT * FROM users WHERE id = ${1}`.first(); // With type parameter const users = await sql`SELECT * FROM users`; // Mutable queries return SQLiteRunResult const result = await sql`INSERT INTO users (name) VALUES (${"Alice"})` as SQLiteRunResult; console.log(result.lastInsertRowId, result.changes); // Synchronous API const users = sql`SELECT * FROM users WHERE age > ${21}`.allSync(); const user = sql`SELECT * FROM users WHERE id = ${userId}`.firstSync(); ``` SQLiteTaggedQuery Methods ### `allSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute a query synchronously that returns rows or metadata based on query type. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteTaggedQueryResult` ### `each()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query and return an async iterator over the rows. Returns: `AsyncIterableIterator` Example ```ts for await (const user of sql`SELECT * FROM users`.each()) { console.log(user.name); } ``` ### `eachSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query synchronously and return an iterator. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `IterableIterator` ### `first()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query and return the first row only. Returns null if no rows match. Returns: `Promise` Example ```ts const user = await sql`SELECT * FROM users WHERE id = ${1}`.first(); ``` ### `firstSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query synchronously and return the first row. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `T | null` ### `values()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query and return rows as arrays of values (Bun-style). Each row is an array where values are in column order. Returns: `Promise` Example ```ts const rows = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]] ``` ### `valuesSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Execute the query synchronously and return rows as arrays of values. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `any[][]` ## Methods ### `SQLite.backupDatabaseAsync(options)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `options` | { destDatabase: [SQLiteDatabase](#sqlitedatabase), destDatabaseName: string, sourceDatabase: [SQLiteDatabase](#sqlitedatabase), sourceDatabaseName: string } | The backup options | Backup a database to another database. Returns: `Promise` > **See:** [https://www.sqlite.org/c3ref/backup_finish.html](https://www.sqlite.org/c3ref/backup_finish.html) ### `SQLite.backupDatabaseSync(options)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `options` | { destDatabase: [SQLiteDatabase](#sqlitedatabase), destDatabaseName: string, sourceDatabase: [SQLiteDatabase](#sqlitedatabase), sourceDatabaseName: string } | The backup options | Backup a database to another database. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` > **See:** [https://www.sqlite.org/c3ref/backup_finish.html](https://www.sqlite.org/c3ref/backup_finish.html) ### `SQLite.deepEqual(a, b)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | | --- | --- | | `a` | `undefined | undefined` | | `b` | `undefined | undefined` | Compares two objects deeply for equality. Returns: `boolean` ### `SQLite.deleteDatabaseAsync(databaseName, directory)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `databaseName` | `string` | The name of the database file to delete. | | `directory`(optional) | `string` | The directory where the database file is located. The default value is `defaultDatabaseDirectory`. | Delete a database file. Returns: `Promise` ### `SQLite.deleteDatabaseSync(databaseName, directory)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `databaseName` | `string` | The name of the database file to delete. | | `directory`(optional) | `string` | The directory where the database file is located. The default value is `defaultDatabaseDirectory`. | Delete a database file. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `void` ### `SQLite.deserializeDatabaseAsync(serializedData, options)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `serializedData` | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The binary array to deserialize from [`SQLiteDatabase.serializeAsync()`](#serializeasyncdatabasename). | | `options`(optional) | [SQLiteOpenOptions](#sqliteopenoptions) | Open options. | Given a `Uint8Array` data and [deserialize to memory database](https://sqlite.org/c3ref/deserialize.html). Returns: `Promise` ### `SQLite.deserializeDatabaseSync(serializedData, options)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `serializedData` | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The binary array to deserialize from [`SQLiteDatabase.serializeSync()`](#serializesyncdatabasename) | | `options`(optional) | [SQLiteOpenOptions](#sqliteopenoptions) | Open options. | Given a `Uint8Array` data and [deserialize to memory database](https://sqlite.org/c3ref/deserialize.html). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteDatabase` ### `SQLite.openDatabaseAsync(databaseName, options, directory)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `databaseName` | `string` | The name of the database file to open. | | `options`(optional) | [SQLiteOpenOptions](#sqliteopenoptions) | Open options. | | `directory`(optional) | `string` | The directory where the database file is located. The default value is `defaultDatabaseDirectory`. This parameter is not supported on web. | Open a database. Returns: `Promise` ### `SQLite.openDatabaseSync(databaseName, options, directory)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `databaseName` | `string` | The name of the database file to open. | | `options`(optional) | [SQLiteOpenOptions](#sqliteopenoptions) | Open options. | | `directory`(optional) | `string` | The directory where the database file is located. The default value is `defaultDatabaseDirectory`. This parameter is not supported on web. | Open a database. > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Returns: `SQLiteDatabase` ## Event Subscriptions ### `SQLite.addDatabaseChangeListener(listener)` Supported platforms: Android, iOS, macOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `listener` | (event: [DatabaseChangeEvent](#databasechangeevent)) => void | A function that receives the `databaseName`, `databaseFilePath`, `tableName` and `rowId` of the modified data. | Add a listener for database changes. > Note: to enable this feature, you must set [`enableChangeListener` to `true`](#sqliteopenoptions) when opening the database. Returns: `EventSubscription` A `Subscription` object that you can call `remove()` on when you would like to unsubscribe the listener. ## Interfaces ### `SQLiteExecuteAsyncResult` Supported platforms: Android, iOS, macOS, tvOS, Web. Extends: [AsyncIterableIterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator) A result returned by [`SQLiteStatement.executeAsync()`](#executeasyncparams). Example The result includes the [`lastInsertRowId`](https://www.sqlite.org/c3ref/last_insert_rowid.html) and [`changes`](https://www.sqlite.org/c3ref/changes.html) properties. You can get the information from the write operations. ```ts const statement = await db.prepareAsync('INSERT INTO test (value) VALUES (?)'); try { const result = await statement.executeAsync(101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); } finally { await statement.finalizeAsync(); } ``` Example The result implements the [`AsyncIterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) interface, so you can use it in `for await...of` loops. ```ts const statement = await db.prepareAsync('SELECT value FROM test WHERE value > ?'); try { const result = await statement.executeAsync<{ value: number }>(100); for await (const row of result) { console.log('row value:', row.value); } } finally { await statement.finalizeAsync(); } ``` Example If your write operations also return values, you can mix all of them together. ```ts const statement = await db.prepareAsync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name'); try { const result = await statement.executeAsync<{ name: string }>('John Doe', 101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); for await (const row of result) { console.log('name:', row.name); } } finally { await statement.finalizeAsync(); } ``` | Property | Type | Description | | --- | --- | --- | | changes | `number` | The number of rows affected. Returned from the [`sqlite3_changes()`](https://www.sqlite.org/c3ref/changes.html) function. | | lastInsertRowId | `number` | The last inserted row ID. Returned from the [`sqlite3_last_insert_rowid()`](https://www.sqlite.org/c3ref/last_insert_rowid.html) function. | SQLiteExecuteAsyncResult Methods ### `getAllAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling [`resetAsync()`](#resetasync). Otherwise, an error will be thrown. Returns: `Promise` ### `getFirstAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling [`resetAsync()`](#resetasync). Otherwise, an error will be thrown. Returns: `Promise` ### `resetAsync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Reset the prepared statement cursor. This will call the [`sqlite3_reset()`](https://www.sqlite.org/c3ref/reset.html) C function under the hood. Returns: `Promise` ### `SQLiteExecuteSyncResult` Supported platforms: Android, iOS, macOS, tvOS, Web. Extends: [IterableIterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) A result returned by [`SQLiteStatement.executeSync()`](#executesyncparams). > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance. Example The result includes the [`lastInsertRowId`](https://www.sqlite.org/c3ref/last_insert_rowid.html) and [`changes`](https://www.sqlite.org/c3ref/changes.html) properties. You can get the information from the write operations. ```ts const statement = db.prepareSync('INSERT INTO test (value) VALUES (?)'); try { const result = statement.executeSync(101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); } finally { statement.finalizeSync(); } ``` Example The result implements the [`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) interface, so you can use it in `for...of` loops. ```ts const statement = db.prepareSync('SELECT value FROM test WHERE value > ?'); try { const result = statement.executeSync<{ value: number }>(100); for (const row of result) { console.log('row value:', row.value); } } finally { statement.finalizeSync(); } ``` Example If your write operations also return values, you can mix all of them together. ```ts const statement = db.prepareSync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name'); try { const result = statement.executeSync<{ name: string }>('John Doe', 101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); for (const row of result) { console.log('name:', row.name); } } finally { statement.finalizeSync(); } ``` | Property | Type | Description | | --- | --- | --- | | changes | `number` | The number of rows affected. Returned from the [`sqlite3_changes()`](https://www.sqlite.org/c3ref/changes.html) function. | | lastInsertRowId | `number` | The last inserted row ID. Returned from the [`sqlite3_last_insert_rowid()`](https://www.sqlite.org/c3ref/last_insert_rowid.html) function. | SQLiteExecuteSyncResult Methods ### `getAllSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling [`resetSync()`](#resetsync). Otherwise, an error will be thrown. Returns: `T[]` ### `getFirstSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling [`resetSync()`](#resetsync). Otherwise, an error will be thrown. Returns: `T | null` ### `resetSync()` Supported platforms: Android, iOS, macOS, tvOS, Web. Reset the prepared statement cursor. This will call the [`sqlite3_reset()`](https://www.sqlite.org/c3ref/reset.html) C function under the hood. Returns: `void` ### `SQLiteOpenOptions` Supported platforms: Android, iOS, macOS, tvOS, Web. Options for opening a database. | Property | Type | Description | | --- | --- | --- | | enableChangeListener(optional) | `boolean` | Whether to call the [`sqlite3_update_hook()`](https://www.sqlite.org/c3ref/update_hook.html) function and enable the `onDatabaseChange` events. You can later subscribe to the change events by [`addDatabaseChangeListener`](#sqliteadddatabasechangelistenerlistener). Default: `false` | | libSQLOptions(optional) | `{ authToken: string, remoteOnly: boolean, url: string }` | Options for libSQL integration. | | useNewConnection(optional) | `boolean` | Whether to create new connection even if connection with the same database name exists in cache. Default: `false` | ### `SQLiteProviderAssetSource` Supported platforms: Android, iOS, macOS, tvOS, Web. | Property | Type | Description | | --- | --- | --- | | assetId | `number` | The asset ID returned from the `require()` call. | | forceOverwrite(optional) | `boolean` | Force overwrite the local database file even if it already exists. Default: `false` | ### `SQLiteRunResult` Supported platforms: Android, iOS, macOS, tvOS, Web. A result returned by [`SQLiteDatabase.runAsync`](#runasyncsource-params) or [`SQLiteDatabase.runSync`](#runsyncsource-params). | Property | Type | Description | | --- | --- | --- | | changes | `number` | The number of rows affected. Returned from the [`sqlite3_changes()`](https://www.sqlite.org/c3ref/changes.html) function. | | lastInsertRowId | `number` | The last inserted row ID. Returned from the [`sqlite3_last_insert_rowid()`](https://www.sqlite.org/c3ref/last_insert_rowid.html) function. | ## Types ### `Changeset` Supported platforms: Android, iOS, macOS, tvOS, Web. Type: [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) A type that represents a changeset. ### `DatabaseChangeEvent` Supported platforms: Android, iOS, macOS, tvOS, Web. The event payload for the listener of [`addDatabaseChangeListener`](#sqliteadddatabasechangelistenerlistener) | Property | Type | Description | | --- | --- | --- | | databaseFilePath | `string` | The absolute file path to the database. | | databaseName | `string` | The database name. The value would be `main` by default and other database names if you use `ATTACH DATABASE` statement. | | rowId | `number` | The changed row ID. | | tableName | `string` | The table name. | ### `SQLiteBindParams` Supported platforms: Android, iOS, macOS, tvOS, Web. Literal Type: `Record` Acceptable values are: Record ### `SQLiteBindValue` Supported platforms: Android, iOS, macOS, tvOS, Web. Literal Type: `union` Bind parameters to the prepared statement. You can either pass the parameters in the following forms: Example A single array for unnamed parameters. ```ts const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?'); const result = await statement.executeAsync(['test1', 789]); const firstRow = await result.getFirstAsync(); ``` Example Variadic arguments for unnamed parameters. ```ts const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?'); const result = await statement.executeAsync('test1', 789); const firstRow = await result.getFirstAsync(); ``` Example A single object for [named parameters](https://www.sqlite.org/lang_expr.html) We support multiple named parameter forms such as `:VVV`, `@VVV`, and `$VVV`. We recommend using `$VVV` because JavaScript allows using `$` in identifiers without escaping. ```ts const statement = await db.prepareAsync('SELECT * FROM test WHERE value = $value AND intValue = $intValue'); const result = await statement.executeAsync({ $value: 'test1', $intValue: 789 }); const firstRow = await result.getFirstAsync(); ``` Acceptable values are: `string` | `number` | `null` | `boolean` | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) ### `SQLiteStorageSetItemUpdateFunction(prevValue)` Supported platforms: Android, iOS, macOS, tvOS, Web. Update function for the [`setItemAsync()`](#setitemasynckey-value) or [`setItemSync()`](#setitemsynckey-value) method. It computes the new value based on the previous value. The function returns the new value to set for the key. | Parameter | Type | Description | | --- | --- | --- | | `prevValue` | `string | null` | The previous value associated with the key, or `null` if the key was not set. | Returns: `string` ### `SQLiteVariadicBindParams` Supported platforms: Android, iOS, macOS, tvOS, Web. Type: [SQLiteBindValue[]](#sqlitebindvalue) --- --- id: statusbar title: StatusBar description: A library that provides the same interface as the React Native StatusBar API, but with slightly different defaults to work great in Expo environments. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-status-bar' packageName: 'expo-status-bar' iconUrl: '/static/images/packages/expo-status-bar.png' platforms: ['android', 'ios', 'tvos', 'web', 'expo-go'] --- # Expo StatusBar A library that provides the same interface as the React Native StatusBar API, but with slightly different defaults to work great in Expo environments. Android, iOS, tvOS, Web, Included in Expo Go `expo-status-bar` gives you a component and imperative interface to control the app status bar to change its text color, background color, hide it, make it translucent or opaque, and apply animations to any of these changes. Exactly what you are able to do with the `StatusBar` component depends on the platform you're using. > **tvOS and web support** > > For **tvOS**, the `expo-status-bar` code will compile and run, but no status bar will show. > > For **web**, there is no API available to control the operating system's status bar, so `expo-status-bar` will do nothing and won't throw an error. ## Installation ```sh npx expo install expo-status-bar ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. ## Usage ```jsx import { StyleSheet, Text, View } from 'react-native'; import { StatusBar } from 'expo-status-bar'; export default function App() { return ( Notice that the status bar has light text! ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#000', alignItems: 'center', justifyContent: 'center', }, text: { color: '#fff', }, }); ``` ## API ```js import { StatusBar } from 'expo-status-bar'; ``` ## Component ### `StatusBar` Supported platforms: Android, iOS, tvOS, Web. Type: React.[Element](https://www.typescriptlang.org/docs/handbook/jsx.html#function-component)<[StatusBarProps](#statusbarprops)\> A component that allows you to configure your status bar without directly calling imperative methods like `setBarStyle`. You will likely have multiple `StatusBar` components mounted in the same app at the same time. For example, if you have multiple screens in your app, you may end up using one per screen. The props of each `StatusBar` component will be merged in the order that they were mounted. This component is built on top of the [StatusBar](https://reactnative.dev/docs/statusbar) component exported from React Native, and it provides defaults that work better for Expo users. StatusBarProps ### `animated` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: `boolean` If the transition between status bar property changes should be animated. Supported for `backgroundColor`, `barStyle` and `hidden`. > **Deprecated:** Due to Android edge-to-edge enforcement, setting the status bar background color is deprecated and has no effect. This will be removed in a future release. ### `backgroundColor` Supported platforms: Android. Optional • Type: `string` The background color of the status bar. ### `hidden` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: `boolean` If the status bar is hidden. ### `hideTransitionAnimation` Supported platforms: iOS. Optional • Type: [StatusBarAnimation](#statusbaranimation) • Default: `'fade'` The transition effect when showing and hiding the status bar using the hidden prop. > **Deprecated:** The status bar network activity indicator is not supported in iOS 13 and later. This will be removed in a future release. ### `networkActivityIndicatorVisible` Supported platforms: iOS. Optional • Type: `boolean` If the network activity indicator should be visible. ### `style` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: [StatusBarStyle](#statusbarstyle) • Default: `'auto'` Sets the color of the status bar text. Default value is `"auto"` which picks the appropriate value according to the active color scheme, eg: if your app is dark mode, the style will be `"light"`. > **Deprecated:** Due to Android edge-to-edge enforcement, setting the status bar as translucent is deprecated and has no effect. This will be removed in a future release. ### `translucent` Supported platforms: Android. Optional • Type: `boolean` If the status bar is translucent. When translucent is set to `true`, the app will draw under the status bar. This is the default behaviour in projects created with Expo tools because it is consistent with iOS. ## Methods > **Deprecated:** Due to Android edge-to-edge enforcement, setting the status bar background color is deprecated and has no effect. This will be removed in a future release. ### `StatusBar.setStatusBarBackgroundColor(backgroundColor, animated)` Supported platforms: Android. | Parameter | Type | Description | | --- | --- | --- | | `backgroundColor` | [ColorValue](https://reactnative.dev/docs/colors) | The background color of the status bar. | | `animated`(optional) | `boolean` | `true` to animate the background color change, `false` to change immediately. | Set the background color of the status bar. Returns: `void` ### `StatusBar.setStatusBarHidden(hidden, animation)` Supported platforms: Android, iOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `hidden` | `boolean` | If the status bar should be hidden. | | `animation`(optional) | [StatusBarAnimation](#statusbaranimation) | Animation to use when toggling hidden, defaults to `'none'`. | Toggle visibility of the status bar. Returns: `void` > **Deprecated:** The status bar network activity indicator is not supported in iOS 13 and later. This will be removed in a future release. ### `StatusBar.setStatusBarNetworkActivityIndicatorVisible(visible)` Supported platforms: iOS. | Parameter | Type | Description | | --- | --- | --- | | `visible` | `boolean` | If the network activity indicator should be visible. | Toggle visibility of the network activity indicator. Returns: `void` ### `StatusBar.setStatusBarStyle(style, animated)` Supported platforms: Android, iOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `style` | [StatusBarStyle](#statusbarstyle) | The color of the status bar text. | | `animated`(optional) | `boolean` | If the transition should be animated. | Set the bar style of the status bar. Returns: `void` > **Deprecated:** Due to Android edge-to-edge enforcement, setting the status bar as translucent is deprecated and has no effect. This will be removed in a future release. ### `StatusBar.setStatusBarTranslucent(translucent)` Supported platforms: Android. | Parameter | Type | Description | | --- | --- | --- | | `translucent` | `boolean` | Whether the app can draw under the status bar. When `true`, content will be rendered under the status bar. This is always `true` on iOS and cannot be changed. | Set the translucency of the status bar. Returns: `void` ## Types ### `StatusBarAnimation` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` Acceptable values are: `'none'` | `'fade'` | `'slide'` ### `StatusBarStyle` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` Acceptable values are: `'auto'` | `'inverted'` | `'light'` | `'dark'` --- --- title: StoreReview description: A library that provides access to native APIs for in-app reviews. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-store-review' packageName: 'expo-store-review' iconUrl: '/static/images/packages/expo-store-review.png' platforms: ['android', 'ios', 'expo-go'] --- # Expo StoreReview A library that provides access to native APIs for in-app reviews. Android, iOS, Included in Expo Go `expo-store-review` is a library that provides access to `ReviewManager` API on Android 5+ and `SKStoreReviewController` API on iOS. It allows you to ask the user to rate your app without leaving the app itself. ## Installation ```sh npx expo install expo-store-review ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. ## Usage It is important that you follow the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews) for iOS and [Guidelines](https://developer.android.com/guide/playcore/in-app-review#when-to-request) for Android when using this API. **Specifically:** - Don't call `StoreReview.requestReview()` from a button - instead try calling it after the user has finished some signature interaction in the app. - Don't spam the user. - Don't request a review when the user is doing something time sensitive like navigating. - Don't ask the user any questions before or while presenting the rating button or card. ### Write reviews #### Android There is no equivalent redirect on Android, you can still open the Play Store to the reviews sections using the query parameter `showAllReviews=true` like this: ```ts const androidPackageName = 'host.exp.exponent'; // Open the Android Play Store in the browser -> redirects to Play Store on Android Linking.openURL( `https://play.google.com/store/apps/details?id=${androidPackageName}&showAllReviews=true` ); // Open the Android Play Store directly Linking.openURL(`market://details?id=${androidPackageName}&showAllReviews=true`); ``` #### iOS You can redirect an app user to the **"Write a Review"** screen for an app in the iOS App Store by using the query parameter `action=write-review`. For example: ```ts const itunesItemId = 982107779; // Open the iOS App Store in the browser -> redirects to App Store on iOS Linking.openURL(`https://apps.apple.com/app/apple-store/id${itunesItemId}?action=write-review`); // Open the iOS App Store directly Linking.openURL( `itms-apps://itunes.apple.com/app/viewContentsUserReviews/id${itunesItemId}?action=write-review` ); ``` ## API ```js import * as StoreReview from 'expo-store-review'; ``` ## Methods ### `StoreReview.hasAction()` Supported platforms: Android, iOS. Returns: `Promise` This returns a promise that fulfills to `true` if `StoreReview.requestReview()` is capable directing the user to some kind of store review flow. If the app config (`app.json`) does not contain store URLs and native store review capabilities are not available then the promise will fulfill to `false`. Example ```ts if (await StoreReview.hasAction()) { // you can call StoreReview.requestReview() } ``` ### `StoreReview.isAvailableAsync()` Supported platforms: Android, iOS. Determines if the platform has the capabilities to use `StoreReview.requestReview()`. Returns: `Promise` This returns a promise fulfills with `boolean`, depending on the platform: - On iOS, it will resolve to `true` unless the app is distributed through TestFlight. - On Android, it will resolve to `true` if the device is running Android 5.0+. - On Web, it will resolve to `false`. ### `StoreReview.requestReview()` Supported platforms: Android, iOS. In ideal circumstances this will open a native modal and allow the user to select a star rating that will then be applied to the App Store, without leaving the app. If the device is running a version of Android lower than 5.0, this will attempt to get the store URL and link the user to it. Returns: `Promise` ### `StoreReview.storeUrl()` Supported platforms: Android, iOS. This uses the `Constants` API to get the `Constants.expoConfig.ios.appStoreUrl` on iOS, or the `Constants.expoConfig.android.playStoreUrl` on Android. On Web this will return `null`. Returns: `string | null` ## Error codes ### `ERR_STORE_REVIEW_FAILED` This error occurs when the store review request was not successful. --- --- title: '@stripe/stripe-react-native' description: A library that provides access to native APIs for integrating Stripe payments. sourceCodeUrl: 'https://github.com/stripe/stripe-react-native' packageName: '@stripe/stripe-react-native' platforms: ['android', 'ios', 'expo-go'] inExpoGo: true --- # @stripe/stripe-react-native A library that provides access to native APIs for integrating Stripe payments. Android, iOS, Included in Expo Go Expo includes support for [`@stripe/stripe-react-native`](https://github.com/stripe/stripe-react-native), which allows you to build delightful payment experiences in your native Android and iOS apps using React Native and Expo. This library provides powerful and customizable UI screens and elements that can be used out-of-the-box to collect your users' payment details. > Migrating from Expo's `expo-payments-stripe` module? [Learn more about how to transition to the new `@stripe/stripe-react-native` library](https://github.com/expo/fyi/blob/main/payments-migration-guide.md#how-to-migrate-from-expo-payments-stripe-to-the-new-stripestripe-react-native-library). [Watch: Universal Full-Stack Expo Stripe Payment Integration](https://www.youtube.com/watch?v=J0tyxUV_omY) — A complete walkthrough for integrating Stripe payments in a universal Expo app across Android, iOS, and web. ## Installation Each Expo SDK version requires a specific `@stripe/stripe-react-native` version. See the [Stripe CHANGELOG](https://github.com/stripe/stripe-react-native/blob/master/CHANGELOG.md) for a mapping of versions. To automatically install the correct version for your Expo SDK version, run: ```sh npx expo install @stripe/stripe-react-native ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. Then, follow the [installation instructions](https://github.com/stripe/stripe-react-native) provided in the library's README or documentation. ### Config plugin setup (optional) If you're using EAS Build, you can do most of your Stripe setup using the `@stripe/stripe-react-native` [config plugin](/config-plugins/introduction). To set up, just add the config plugin to the `plugins` array of your **app.json** or **app.config.js** as shown below, then rebuild the app. ```json { "expo": { ... "plugins": [ [ "@stripe/stripe-react-native", { "merchantIdentifier": string | string [], "enableGooglePay": boolean } ] ], } } ``` - **merchantIdentifier**: iOS only. This is the [Apple merchant ID obtained here](https://docs.stripe.com/apple-pay?platform=react-native). Otherwise, Apple Pay will not work as expected. If you have multiple merchantIdentifiers, you can set them in an array. - **enableGooglePay**: Android only. Boolean indicating whether or not Google Pay is enabled. Defaults to `false`. ## Example Trying out Stripe takes just a few seconds. Connect to [this Snack](https://snack.expo.dev/@charliecruzan/stripe-react-native-example?platform=mydevice) on your device. Under the hood, that example connects to a Glitch server for payment processing. ## Usage For usage information and detailed documentation, see the following resources: - [Stripe's React Native SDK reference](https://stripe.dev/stripe-react-native/api-reference/index.html) - [Stripe's React Native GitHub repo](https://github.com/stripe/stripe-react-native) - [Stripe's example React Native app](https://github.com/stripe/stripe-react-native/tree/master/example) ### Common issues #### Browser pop-ups are not redirecting back to my app If you're relying on redirects, you'll need to pass in a `urlScheme` to `initStripe`. To make sure you always use the proper `urlScheme`, pass in: ```js import * as Linking from 'expo-linking'; import Constants from 'expo-constants'; urlScheme: Constants.appOwnership === 'expo' ? Linking.createURL('/--/') : Linking.createURL(''), ``` [`Linking.createURL()`](/versions/latest/sdk/linking#createurloptions) will ensure you're using the proper scheme, whether you're running in Expo Go or your production app. `'/--/'` is necessary in Expo Go because it indicates that the substring after it corresponds to the deep link path, and is not part of the path to the app itself. #### PaymentSheet localization on iOS On Android, the translation of `PaymentSheet` is automatically detected based on a device's language settings. On iOS, you must enable `CFBundleAllowMixedLocalizations` and add the preferred language using `CFBundleLocalizations` under [`ios.infoPlist`](/versions/latest/config/app#infoplist) in the app config: ```json { "expo": { "ios": { "infoPlist": { "CFBundleAllowMixedLocalizations": true, "CFBundleLocalizations": ["fr"] ... } ... } } } ``` ## Limitations ### Google Pay Google Pay **is not** supported in [Expo Go](https://expo.dev/go). To use Google Pay, you must create a [development build](/develop/development-builds/create-a-build). This can be done with [EAS Build](/build/introduction), or locally by running `npx expo run:android`. ### Apple Pay Apple Pay **is not** supported in [Expo Go](https://expo.dev/go). To use Apple Pay, you must create a [development build](/develop/development-builds/create-a-build). This can be done with [EAS Build](/build/introduction), or locally by running `npx expo run:ios`. --- --- title: react-native-svg description: A library that allows using SVGs in your app. sourceCodeUrl: 'https://github.com/react-native-community/react-native-svg' packageName: react-native-svg platforms: ['android', 'ios', 'macos', 'web', 'tvos', 'expo-go'] inExpoGo: true --- # react-native-svg A library that allows using SVGs in your app. Android, iOS, macOS, tvOS, Web, Included in Expo Go `react-native-svg` allows you to use SVGs in your app, with support for interactivity and animation. ## Installation ```sh npx expo install react-native-svg ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. Then, follow the [installation instructions](https://github.com/react-native-community/react-native-svg#with-react-native-cli) provided in the library's README or documentation. ## API ```js import * as Svg from 'react-native-svg'; ``` ### `Svg` A set of drawing primitives such as `Circle`, `Rect`, `Path`, `ClipPath`, and `Polygon`. It supports most SVG elements and properties. The implementation is provided by [react-native-svg](https://github.com/react-native-community/react-native-svg), and documentation is provided in that repository. ```tsx import Svg, { Circle, Rect } from 'react-native-svg'; export default function SvgComponent(props) { return ( ); } ``` ### Tips Here are some helpful links that will get you moving fast! - Looking for SVGs? Try [Lucide](https://lucide.dev/). - Create or modify your own SVGs for free using [Figma](https://www.figma.com/). - Optimize your SVG with [SVGOMG](https://jakearchibald.github.io/svgomg/). This will make the code smaller and easier to work with. Be sure not to remove the `viewbox` for best results on Android. - Convert your SVG to an Expo component in the browser using [SVGR](https://react-svgr.com/playground/?native=true&typescript=true). ## Learn more [Visit official documentation](https://github.com/software-mansion/react-native-svg) — Get full information on API and its usage. --- --- title: Symbols description: A library that allows access to native symbols. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-symbols' packageName: 'expo-symbols' iconUrl: '/static/images/packages/expo-symbols.png' platforms: ['android', 'ios', 'tvos', 'web', 'expo-go'] isBeta: true --- # Expo Symbols A library that allows access to native symbols. Android, iOS, tvOS, Web, Included in Expo Go > This library is currently in [beta](/more/release-statuses#beta) and subject to breaking changes. `expo-symbols` provides access to native symbol libraries across platforms. On iOS and tvOS, it uses [SF Symbols](https://developer.apple.com/sf-symbols/). On Android and web, it uses [Material Symbols](https://fonts.google.com/icons). ## Installation ```sh npx expo install expo-symbols ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. ## Usage ### Cross-platform symbols Pass an object with per-platform symbol names to render symbols on all platforms. Browse available iOS symbols in the [Apple SF Symbols app](https://developer.apple.com/sf-symbols/) and Android/web symbols at [Google Material Symbols](https://fonts.google.com/icons). ```jsx import { SymbolView } from 'expo-symbols'; import { StyleSheet, View } from 'react-native'; export default function App() { return ( ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', }, symbol: { width: 35, height: 35, margin: 5, }, }); ``` If you only pass a string, it is treated as an SF Symbol name and renders only on iOS. On Android and web, nothing will be rendered unless you provide a `fallback`: ```jsx { /* iOS-only: pass an SF Symbol name directly */ } ; { /* Use fallback for platforms where the symbol is not defined */ } ?} />; ``` ### Weights On iOS, pass a weight string directly. On Android, import a weight object from `expo-symbols/androidWeights`: ```jsx import bold from 'expo-symbols/androidWeights/bold'; ; ``` Available weight imports: `bold`, `semiBold`, `medium`, `regular`, `light`, `extraLight`, `thin`. ## API ```js import { SymbolView } from 'expo-symbols'; ``` ## Component ### `SymbolView` Supported platforms: Android, iOS, tvOS, Web. Type: React.[Element](https://www.typescriptlang.org/docs/handbook/jsx.html#function-component)<[SymbolViewProps](#symbolviewprops)\> SymbolViewProps ### `animationSpec` Supported platforms: iOS. Optional • Type: [AnimationSpec](#animationspec) The animation configuration to apply to the symbol. ### `colors` Supported platforms: iOS. Optional • Literal type: `union` An array of colors to use when the [`SymbolType`](#symboltype) is `palette`. Acceptable values are: [ColorValue](https://reactnative.dev/docs/colors) | [ColorValue[]](https://reactnative.dev/docs/colors) ### `fallback` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: `React.ReactNode` Fallback to render when a symbol for the given platform is not defined. ### `name` Supported platforms: Android, iOS, tvOS, Web. Literal type: `union` The name of the symbol. iOS Symbols can be viewed in the [Apple SF Symbols app](https://developer.apple.com/sf-symbols/). Acceptable values are: [SFSymbol](https://github.com/nandorojo/sf-symbols-typescript) | { android: AndroidSymbol, ios: [SFSymbol](https://github.com/nandorojo/sf-symbols-typescript), web: AndroidSymbol } ### `resizeMode` Supported platforms: iOS. Optional • Type: [ContentMode](#contentmode) • Default: `'scaleAspectFit'` Determines how the image should be resized to fit its container. ### `scale` Supported platforms: iOS. Optional • Type: [SymbolScale](#symbolscale) • Default: `'unspecified'` The scale of the symbol to render. ### `size` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: `number` • Default: `24` The size of the symbol. ### `tintColor` Supported platforms: Android, iOS, tvOS, Web. Optional • Type: [ColorValue](https://reactnative.dev/docs/colors) The tint color to apply to the symbol. ### `type` Supported platforms: iOS. Optional • Type: [SymbolType](#symboltype) • Default: `'monochrome'` Determines the symbol variant to use. ### `weight` Supported platforms: Android, iOS, tvOS, Web. Optional • Literal type: `union` • Default: `'unspecified'` The weight of the symbol to render. On Android and web import from `expo-symbols/androidWeights/{weight}`. Acceptable values are: [SymbolWeight](#symbolweight) | { android: AndroidSymbolWeight, ios: [SymbolWeight](#symbolweight) } #### Inherited Props - [ViewProps](https://reactnative.dev/docs/view#props) ## Methods ### `Symbol.unstable_getMaterialSymbolSourceAsync(symbol, size, color)` Supported platforms: Android. | Parameter | Type | | --- | --- | | `symbol` | `See description for available values.` | | `size` | `number` | | `color` | `string` | Renders a Material Symbol to an image source. Returns: `Promise` ## Types ### `AnimationEffect` Supported platforms: Android, iOS, tvOS, Web. | Property | Type | Description | | --- | --- | --- | | direction(optional) | `'up' | 'down'` | The direction of the animation. | | type | [AnimationType](#animationtype) | The type of animation to apply to the symbol. | | wholeSymbol(optional) | `boolean` | Whether the entire symbol should animate or just the individual layers. Default: `false` | ### `AnimationSpec` Supported platforms: Android, iOS, tvOS, Web. The animation configuration to apply to the symbol. | Property | Type | Description | | --- | --- | --- | | effect(optional) | [AnimationEffect](#animationeffect) | The effect to apply to the symbol. | | repeatCount(optional) | `number` | The number of times the animation should repeat. | | repeating(optional) | `boolean` | If the animation should repeat. | | speed(optional) | `number` | The duration of the animation in seconds. | | variableAnimationSpec(optional) | [VariableAnimationSpec](#variableanimationspec) | An object that specifies how the symbol’s layers should animate. | ### `AnimationType` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` The type of animation to apply to the symbol. Acceptable values are: `'bounce'` | `'pulse'` | `'scale'` ### `ContentMode` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` Determines how the image should be resized to fit its container. Acceptable values are: `'scaleToFill'` | `'scaleAspectFit'` | `'scaleAspectFill'` | `'redraw'` | `'center'` | `'top'` | `'bottom'` | `'left'` | `'right'` | `'topLeft'` | `'topRight'` | `'bottomLeft'` | `'bottomRight'` ### `SymbolScale` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` The scale of the symbol to render. Acceptable values are: `'default'` | `'unspecified'` | `'small'` | `'medium'` | `'large'` ### `SymbolType` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` Determines the symbol variant to use. - `'monochrome'` - Creates a color configuration that specifies that the symbol image uses its monochrome variant. - `'hierarchical'` - Creates a color configuration with a color scheme that originates from one color. - `'palette'` - Creates a color configuration with a color scheme from a palette of multiple colors. - `'multicolor'` - Creates a color configuration that specifies that the symbol image uses its multicolor variant, if one exists. Acceptable values are: `'monochrome'` | `'hierarchical'` | `'palette'` | `'multicolor'` ### `SymbolWeight` Supported platforms: Android, iOS, tvOS, Web. Literal Type: `string` The weight of the symbol to render. Acceptable values are: `'unspecified'` | `'ultraLight'` | `'thin'` | `'light'` | `'regular'` | `'medium'` | `'semibold'` | `'bold'` | `'heavy'` | `'black'` ### `VariableAnimationSpec` Supported platforms: Android, iOS, tvOS, Web. A variable color animation draws attention to a symbol by changing the opacity of the symbol’s layers. You can choose to apply the effect to layers either cumulatively or iteratively. For cumulative animations, each layer’s opacity remains changed until the end of the animation cycle. For iterative animations, each layer’s opacity changes briefly before returning to its original state. These effects are compounding, each value set to `true` will add an additional effect. | Property | Type | Description | | --- | --- | --- | | cumulative(optional) | `boolean` | This effect enables each successive variable layer, and the layer remains enabled until the end of the animation cycle. This effect cancels the iterative variant. | | dimInactiveLayers(optional) | `boolean` | An effect that dims inactive layers of a symbol. This effect draws inactive layers with reduced, but nonzero, opacity. | | hideInactiveLayers(optional) | `boolean` | An effect that hides inactive layers of a symbol. This effect hides inactive layers completely, rather than drawing them with reduced, but nonzero, opacity. | | iterative(optional) | `boolean` | An effect that momentarily enables each layer of a symbol in sequence. | | nonReversing(optional) | `boolean` | An effect that doesn’t reverse each time it repeats. | | reversing(optional) | `boolean` | An effect that reverses each time it repeats. | --- --- title: SystemUI description: A library that allows interacting with system UI elements. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-system-ui' packageName: 'expo-system-ui' platforms: ['android', 'ios', 'tvos', 'web'] --- # Expo SystemUI A library that allows interacting with system UI elements. Android, iOS, tvOS, Web `expo-system-ui` enables you to interact with UI elements that fall outside of the React tree. Specifically the root view background color, and locking the user interface style globally on Android. ## Installation ```sh npx expo install expo-system-ui ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. ## Configuration in app config You can configure `expo-system-ui` using its built-in [config plugin](/config-plugins/introduction) if you use config plugins in your project ([Continuous Native Generation (CNG)](/workflow/continuous-native-generation)). The plugin allows you to configure [`userInterfaceStyle`](/versions/latest/config/app#userinterfacestyle) on Android and [`backgroundColor`](/versions/latest/config/app#backgroundcolor) on iOS properties from [app config](/versions/latest/config/app). These properties cannot be set at runtime and require building a new app binary to take effect. If your app does **not** use CNG, then you'll need to manually configure the library. ### Example app.json with config plugin ```json { "expo": { "backgroundColor": "#ffffff", "userInterfaceStyle": "light", "ios": { "backgroundColor": "#ffffff", } "android": { "userInterfaceStyle": "light" }, "plugins": ["expo-system-ui"], } } ``` Are you using this library in an existing React Native app? If you're not using Continuous Native Generation ([CNG](/workflow/continuous-native-generation)) or you're using native **android** and **ios** project manually, then you need to add the following configuration to your native project: **Android** To apply `userInterfaceStyle` on Android, you need to add the `expo_system_ui_user_interface_style` configuration **android/app/src/main/res/values/strings.xml**: ```xml light ``` **iOS** To apply `backgroundColor` on iOS, you need to add the `UIUserInterfaceStyle` configuration in **ios/your-app/Info.plist**: ```xml UIUserInterfaceStyle Light ``` ## API ```js import * as SystemUI from 'expo-system-ui'; ``` ## Methods ### `SystemUI.getBackgroundColorAsync()` Supported platforms: Android, iOS, tvOS, Web. Gets the root view background color. Returns: `Promise` Current root view background color in hex format. Returns `null` if the background color is not set. Example ```ts const color = await SystemUI.getBackgroundColorAsync(); ``` ### `SystemUI.setBackgroundColorAsync(color)` Supported platforms: Android, iOS, tvOS, Web. | Parameter | Type | Description | | --- | --- | --- | | `color` | [ColorValue](https://reactnative.dev/docs/colors) | null | Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color). | Changes the root view background color. Call this function in the root file outside of your component. Returns: `Promise` Example ```ts SystemUI.setBackgroundColorAsync("black"); ``` --- --- title: TaskManager description: A library that provides support for tasks that can run in the background. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-task-manager' packageName: 'expo-task-manager' platforms: ['android', 'ios', 'tvos', 'expo-go'] --- # Expo TaskManager A library that provides support for tasks that can run in the background. Android, iOS, tvOS, Included in Expo Go `expo-task-manager` provides an API that allows you to manage long-running tasks, in particular those tasks that can run while your app is in the background. Some features of this library are used by other libraries under the hood. Here is a list of Expo SDK libraries that use `TaskManager`. ## Libraries using Expo TaskManager - [Location](/versions/latest/sdk/location) - [BackgroundTask](/versions/latest/sdk/background-task) - [BackgroundFetch](/versions/latest/sdk/background-fetch) - [Notifications](/versions/latest/sdk/notifications) ## Installation ```sh npx expo install expo-task-manager ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. > You can test `TaskManager` in the Expo Go app. However, check the documentation of each [library](/versions/latest/sdk/task-manager#libraries-using-expo-taskmanager) that uses `TaskManager` to confirm whether it supports testing in Expo Go. ## Configuration Standalone apps need some extra configuration: on iOS, each background feature requires a special key in `UIBackgroundModes` array in your **Info.plist** file. Read more about how to configure this in the reference for each of the [libraries](/versions/latest/sdk/task-manager#libraries-using-expo-taskmanager) that use `TaskManager`. ## Example ```jsx import React from 'react'; import { Button, View, StyleSheet } from 'react-native'; import * as TaskManager from 'expo-task-manager'; import * as Location from 'expo-location'; const LOCATION_TASK_NAME = 'background-location-task'; const requestPermissions = async () => { const { status: foregroundStatus } = await Location.requestForegroundPermissionsAsync(); if (foregroundStatus === 'granted') { const { status: backgroundStatus } = await Location.requestBackgroundPermissionsAsync(); if (backgroundStatus === 'granted') { await Location.startLocationUpdatesAsync(LOCATION_TASK_NAME, { accuracy: Location.Accuracy.Balanced, }); } } }; const PermissionsButton = () => (

Hello Expo!