How to Use arrayRemove in Firestore: Syntax and Examples

Use arrayRemove from Firestore's FieldValue to delete specific elements from an array field in a document. It removes all instances of the given value(s) atomically without affecting other array items.

Syntax

The arrayRemove function is used with Firestore's updateDoc method to remove one or more elements from an array field in a document. It takes one or more values as arguments and removes all matching elements from the array.

• arrayRemove(value1, value2, ...): Removes the specified values from the array field.
• updateDoc(docRef, { field: arrayRemove(...) }): Updates the document's array field by removing the values.

javascript

import { getFirestore, doc, updateDoc, arrayRemove } from "firebase/firestore";

const db = getFirestore();
const docRef = doc(db, "collectionName", "docId");

await updateDoc(docRef, {
  arrayField: arrayRemove("valueToRemove")
});

Example

This example shows how to remove the string "apple" from an array field named fruits in a Firestore document. It updates the document without affecting other array items.

javascript

import { initializeApp } from "firebase/app";
import { getFirestore, doc, updateDoc, arrayRemove } from "firebase/firestore";

const firebaseConfig = {
  // your config here
};

const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

async function removeFruit() {
  const docRef = doc(db, "users", "user123");
  await updateDoc(docRef, {
    fruits: arrayRemove("apple")
  });
  console.log("Removed 'apple' from fruits array.");
}

removeFruit();

Output

Removed 'apple' from fruits array.

Common Pitfalls

Common mistakes when using arrayRemove include:

• Trying to remove an element that does not exist in the array (no error, but no change).
• Passing an object with different references but same content (only exact matches are removed).
• Using arrayRemove on a field that is not an array (causes an error).

Always ensure the field is an array and the values match exactly what you want to remove.

javascript

import { updateDoc, arrayRemove } from "firebase/firestore";

// Wrong: removing an object with different reference
await updateDoc(docRef, {
  items: arrayRemove({ id: 1, name: "item" }) // won't remove if object reference differs
});

// Right: remove by exact object reference or use unique identifiers
await updateDoc(docRef, {
  items: arrayRemove(existingObjectReference)
});

Quick Reference

Method	Description
arrayRemove(value1, value2, ...)	Removes specified values from an array field.
updateDoc(docRef, { field: arrayRemove(...) })	Updates document to remove values from array field.
Works atomically	Ensures safe concurrent updates without overwriting.
No error if value not found	Operation silently does nothing if value is absent.
Exact match required	Only removes elements exactly equal to given values.

Key Takeaways

Use FieldValue.arrayRemove to atomically remove specific elements from Firestore array fields.

arrayRemove removes all instances of the given value(s) without affecting other array items.

Ensure the field is an array and values match exactly to avoid no changes.

No error occurs if the value to remove is not present in the array.

Use updateDoc with arrayRemove to safely update documents without overwriting the entire array.