Skip to main content

​
get

Retrieve all collections for a specific user.
​
userId
string
required
The unique identifier of the user whose collections to retrieve
​
collections
array
Array of collection objects belonging to the user
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";

function MyCollections() {
  const collections = useQuery(api.collections.get, { 
    userId: "user_123" 
  });

  return (
    <div>
      {collections?.map((collection) => (
        <div key={collection._id}>{collection.name}</div>
      ))}
    </div>
  );
}

​
getCollection

Retrieve a single collection with all its verses.
​
id
Id<'collections'>
required
The unique identifier of the collection to retrieve
​
userId
string
required
The user ID requesting access to verify ownership
​
response
object
This function validates that the requesting user owns the collection before returning data.
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function CollectionDetail({ collectionId }: { collectionId: Id<"collections"> }) {
  const data = useQuery(api.collections.getCollection, {
    id: collectionId,
    userId: "user_123"
  });

  if (!data) return <div>Loading...</div>;

  return (
    <div>
      <h2>{data.collection.name}</h2>
      <div>
        {data.verses.map((verse) => (
          <p key={verse._id}>{verse.verseText}</p>
        ))}
      </div>
    </div>
  );
}

​
createCollection

Create a new verse collection.
​
name
string
required
The name for the new collection
​
userId
string
required
The unique identifier of the user creating the collection
​
collectionId
Id<'collections'>
The unique identifier of the newly created collection
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { useState } from "react";

function CreateCollection() {
  const [name, setName] = useState("");
  const createCollection = useMutation(api.collections.createCollection);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const collectionId = await createCollection({
      name,
      userId: "user_123"
    });
    console.log("Created collection:", collectionId);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input 
        value={name} 
        onChange={(e) => setName(e.target.value)}
        placeholder="Collection name"
      />
      <button type="submit">Create</button>
    </form>
  );
}

​
updateCollection

Update an existing collection’s name.
​
id
Id<'collections'>
required
The unique identifier of the collection to update
​
name
string
required
The new name for the collection
​
userId
string
required
The user ID requesting the update to verify ownership
​
response
null
Returns null on successful update
This function validates that the requesting user owns the collection before allowing the update.
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function RenameCollection({ 
  collectionId, 
  currentName 
}: { 
  collectionId: Id<"collections">;
  currentName: string;
}) {
  const updateCollection = useMutation(api.collections.updateCollection);
  const [name, setName] = useState(currentName);

  const handleUpdate = async () => {
    await updateCollection({
      id: collectionId,
      name,
      userId: "user_123"
    });
  };

  return (
    <div>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <button onClick={handleUpdate}>Save</button>
    </div>
  );
}

​
deleteCollection

Delete a collection and all its contents.
​
id
Id<'collections'>
required
The unique identifier of the collection to delete
​
userId
string
required
The user ID requesting the deletion to verify ownership
​
response
null
Returns null on successful deletion
This function validates that the requesting user owns the collection before allowing deletion. Note that deleting a collection does not automatically delete associated verses from the collectionVerses table.
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function DeleteCollectionButton({ 
  collectionId 
}: { 
  collectionId: Id<"collections">;
}) {
  const deleteCollection = useMutation(api.collections.deleteCollection);

  const handleDelete = async () => {
    if (confirm("Are you sure you want to delete this collection?")) {
      await deleteCollection({
        id: collectionId,
        userId: "user_123"
      });
    }
  };

  return <button onClick={handleDelete}>Delete Collection</button>;
}