Overview
Teak supports 8 card types: text, link, image, video, audio, document, palette, and quote. You can either specify the type explicitly or let Teak automatically detect it.
Card Types
Tab Title
Tab Title
Tab Title
Tab Title
Tab Title
Tab Title
Tab Title
Tab Title
Basic text notes and ideas.{
content: "My brilliant idea",
type: "text"
}
Web URLs with automatic metadata extraction.{
content: "Check this out",
url: "https://example.com",
type: "link"
}
Link cards automatically fetch:
- Page title and description
- Open Graph images
- Category classification (book, article, product, etc.)
- Provider-specific structured data
Photos, illustrations, and visual content.{
content: "Sunset photo",
type: "image",
fileId: storageId
}
SVG images automatically get thumbnail generation for palette extraction.
Video files with automatic thumbnail generation.{
content: "Tutorial video",
type: "video",
fileId: storageId,
metadata: {
duration: 180,
width: 1920,
height: 1080
}
}
Audio recordings and voice memos.{
content: "Meeting notes",
type: "audio",
fileId: storageId,
metadata: {
duration: 300
}
}
PDFs and document files.{
content: "Research paper",
type: "document",
fileId: storageId,
metadata: {
fileName: "paper.pdf",
fileSize: 1024000
}
}
Color palettes extracted from hex codes or text.{
content: "Sunset palette",
type: "palette",
colors: [
{ hex: "#FF6B35", name: "Coral" },
{ hex: "#F7931E", name: "Orange" },
{ hex: "#FDC830", name: "Yellow" }
]
}
If you don’t provide colors, Teak automatically extracts them from the content, notes, or tags.
Inspirational quotes and excerpts.{
content: "Be the change you wish to see",
type: "quote"
}
Wrap text in quotes (”) and Teak will auto-detect it as a quote card.
Auto-Detection
When you omit the type parameter, Teak uses intelligent classification:
URL Extraction
If the content contains a URL, it’s extracted and cleaned:// Input
{ content: "Check out https://example.com - really cool!" }
// Processed
{
content: "Check out - really cool!",
url: "https://example.com",
type: "link" // auto-detected
}
Quote Detection
Text wrapped in quotation marks becomes a quote:// Input
{ content: '"To be or not to be"' }
// Processed
{
content: "To be or not to be",
type: "quote" // auto-detected
}
File Type Detection
When a fileId is provided, MIME type determines the card type:| MIME Type | Card Type |
|---|
| image/* | image |
| video/* | video |
| audio/* | audio |
| application/pdf | document |
AI Classification
For ambiguous cases, an AI classifier analyzes the content and assigns the most appropriate type with a confidence score.
Creating Cards
From Code
import { api } from "@teak/convex";
import { useMutation } from "convex/react";
function MyComponent() {
const createCard = useMutation(api.card.createCard.createCard);
const handleCreate = async () => {
await createCard({
content: "My new card",
type: "text",
tags: ["ideas", "todo"],
notes: "Additional context here"
});
};
}
With Files
Upload to Storage
const fileId = await storage.upload(file);
Create Card with File Reference
await createCard({
content: "My uploaded file",
fileId: fileId,
type: "image", // or let auto-detection handle it
metadata: {
fileName: file.name,
fileSize: file.size,
mimeType: file.type
}
});
| Field | Type | Description | Example |
|---|
content | string | Main text content | "My idea" |
type | CardType | Card type (optional) | "text" |
url | string | Associated URL | "https://..." |
fileId | Id<“_storage”> | Convex storage ID | k1abc... |
thumbnailId | Id<“_storage”> | Custom thumbnail | k2def... |
tags | string[] | User tags | ["work", "urgent"] |
notes | string | Additional notes | "Follow up next week" |
metadata | object | Custom metadata | { source: "email" } |
colors | Color[] | Palette colors | [{ hex: "#FF0000" }] |
Processing Pipeline
After creation, cards enter an automated processing workflow:
All processing happens asynchronously. You can query processingStatus to track progress.
Rate Limits
Teak enforces creation limits to ensure quality:
- Free tier: 200 cards maximum
- Rate limiting: Prevents spam creation
// Rate limit error example
try {
await createCard({ content: "Card" });
} catch (error) {
if (error.code === "CARD_LIMIT_REACHED") {
// Show upgrade prompt
} else if (error.code === "RATE_LIMITED") {
// Show "slow down" message
}
}
Best Practices
Let auto-detection work for you: Omit type for simpler code and smarter classification.
Include context in notes: The notes field helps AI generate better tags and summaries.
File size limit: Maximum 20MB per file. Check MAX_FILE_SIZE constant.
Batch uploads: Use MAX_FILES_PER_UPLOAD (5 files) to create multiple cards efficiently.
Source Reference
The card creation logic is in:
packages/convex/card/createCard.ts:61-189 - Main handlerpackages/convex/workflows/cardProcessing.ts:43-298 - Processing workflow