Skip to main content

Overview

The Milestones API allows you to track your baby’s developmental achievements. Milestones can be predefined (based on age-appropriate development) or custom (created by caregivers).

Milestone Schema

interface Milestone {
  _id: Id<"milestones">;
  babyId: Id<"babyProfiles">;
  key: string; // Unique identifier
  title: string;
  category: string; // "motor", "language", "social", "cognitive"
  achievedAt?: string; // ISO 8601
  note?: string;
  photoIds?: string[];
  videoIds?: string[];
  isCustom?: boolean;
  createdAt: string;
}

List Milestones

Retrieve all milestones for a baby profile.
import { useQuery } from "convex/react";
import { api } from "./convex/_generated/api";

const milestones = useQuery(api.milestones.list, {
  babyId
});

// Response:
[
  {
    _id: "...",
    babyId: "...",
    key: "first_smile",
    title: "First Social Smile",
    category: "social",
    achievedAt: "2024-02-20T10:30:00Z",
    note: "Big smile at grandma!",
    photoIds: ["photo1", "photo2"],
    createdAt: "2024-02-20T10:30:00Z"
  }
]

Parameters

babyId
Id<'babyProfiles'>
required
The baby profile ID

Response

milestones
array
Array of milestone objects

Mark Milestone Achieved

Mark a predefined milestone as achieved.
const achieve = useMutation(api.milestones.achieve);

await achieve({
  babyId,
  key: "first_smile",
  title: "First Social Smile",
  category: "social",
  achievedAt: "2024-02-20T10:30:00Z",
  note: "Such a precious moment!",
  photoIds: ["photo1"]
});

Parameters

babyId
Id<'babyProfiles'>
required
The baby profile ID
key
string
required
Unique milestone key (e.g., “first_smile”, “sits_unsupported”)
title
string
required
Milestone title (e.g., “First Social Smile”)
category
string
required
Category: “motor”, “language”, “social”, or “cognitive”
achievedAt
string
ISO 8601 timestamp when achieved. Defaults to current time if omitted.
note
string
Optional note about the milestone
photoIds
string[]
Array of photo IDs to attach
videoIds
string[]
Array of video IDs to attach

Response

milestoneId
Id<'milestones'>
The milestone ID (creates new or updates existing)
If a milestone with the same key already exists for this baby, it will be updated instead of creating a duplicate.

Create Custom Milestone

Create a custom milestone unique to your baby.
const createCustom = useMutation(api.milestones.createCustom);

await createCustom({
  babyId,
  title: "Recognized Grandpa's Voice",
  category: "social",
  achievedAt: "2024-03-05T15:00:00Z",
  note: "Turned head toward grandpa when he called",
  photoIds: []
});

Parameters

babyId
Id<'babyProfiles'>
required
The baby profile ID
title
string
required
Custom milestone title
category
string
required
Category: “motor”, “language”, “social”, or “cognitive”
achievedAt
string
Achievement timestamp (defaults to now)
note
string
Optional note
photoIds
string[]
Photo attachments
videoIds
string[]
Video attachments

Response

milestoneId
Id<'milestones'>
The newly created custom milestone ID
Custom milestones are automatically assigned a unique key (e.g., custom_1709654400_abc123) and marked with isCustom: true.

Update Milestone

Update an existing milestone’s details.
const updateMilestone = useMutation(api.milestones.updateMilestone);

await updateMilestone({
  id: milestoneId,
  note: "Updated note with more details",
  photoIds: ["photo1", "photo2", "photo3"]
});

Parameters

id
Id<'milestones'>
required
The milestone ID to update
achievedAt
string
Updated achievement date
note
string
Updated note
photoIds
string[]
Updated photo IDs (replaces existing)
videoIds
string[]
Updated video IDs (replaces existing)

Delete Milestone

Delete a milestone permanently.
const deleteMilestone = useMutation(api.milestones.deleteMilestone);

await deleteMilestone({
  id: milestoneId
});

Parameters

id
Id<'milestones'>
required
The milestone ID to delete
Deleting a milestone also removes all associated photos and videos. This action cannot be undone.

Milestone Categories

Motor

Physical development milestones:
  • Rolling over
  • Sitting unsupported
  • Crawling
  • Walking
  • Fine motor skills (grasping, pincer grip)

Language

Communication milestones:
  • Cooing and babbling
  • First words
  • Two-word phrases
  • Sentence formation
  • Understanding commands

Social

Social and emotional development:
  • Social smiles
  • Recognizing caregivers
  • Playing with others
  • Sharing and turn-taking
  • Expressing emotions

Cognitive

Mental development milestones:
  • Object permanence
  • Cause and effect
  • Problem solving
  • Memory skills
  • Sorting and categorizing

Common Predefined Milestones

0-3 Months

  • first_smile - First Social Smile
  • tracks_objects - Tracks Moving Objects
  • lifts_head - Lifts Head When on Tummy
  • coos - Makes Cooing Sounds

4-6 Months

  • rolls_over - Rolls Over Both Ways
  • sits_with_support - Sits With Support
  • reaches_for_toys - Reaches for Toys
  • babbles - Babbles with Consonants

7-9 Months

  • sits_unsupported - Sits Without Support
  • crawls - Crawls or Scoots
  • transfers_objects - Transfers Objects Between Hands
  • responds_to_name - Responds to Name

10-12 Months

  • stands_with_support - Stands With Support
  • first_steps - Takes First Steps
  • first_word - Says First Word
  • waves_bye - Waves Bye-Bye
Age ranges are approximate. Every baby develops at their own pace. Consult your pediatrician if you have concerns.

Best Practices

Capture achievements when they happen. Use the achievedAt field to backdate if needed.
Visual memories make milestone tracking more meaningful. Attach photos and videos to preserve these moments.
Add details like who was there, what happened, or the baby’s reaction to make memories richer.
Don’t limit yourself to predefined milestones. Create custom ones for unique achievements like “First time at the beach” or “Met cousin for first time”.
Babies develop in multiple areas simultaneously. Track motor, language, social, and cognitive milestones for a complete picture.

Milestones Guide

Feature guide and tracking tips

Baby Profiles

Baby profile management

Events

Track daily activities

Media Upload

Learn about photo and video attachments

Build docs developers (and LLMs) love