How to Use Moodlith

A complete guide to logging moods, connecting health data, and getting the most out of your insights.

Quick Start

Log Your First Mood — Tap the '+' button to log how you're feeling. Choose an emoji, adjust the slider, and optionally add tags or notes.

Explore Your Dashboard — View wellness recommendations, health metrics, and recent entries. Recommendations improve as you log more moods.

Check Your Journey — Navigate to 'My Journey' to see mood trends, patterns, and correlations over time.

Review Insights — Visit 'AI Insights' to see personalized recommendations and discover what affects your mood.

Recommendations may take a few seconds to generate. Rule-based recommendations appear immediately while AI-enhanced ones load in the background.

How to Log Moods

Emoji Selection — Choose an emoji that represents how you're feeling.
Mood Slider (0–100) — Fine-tune your mood intensity. 0 is very low, 50 is neutral, 100 is very high.
Tags (Optional) — Add context with tags like "Work," "Exercise," or "Social."
Notes (Optional) — Add detailed thoughts or context to help identify patterns.
Optional Context — Enable health metrics (sleep, steps, HRV) or weather in Settings to include with entries. This data helps generate better insights.
Edit Mood Entries — Swipe left on any mood entry to edit or delete. You can change the mood, tags, and notes. Weather and health metrics are read-only, since they're a snapshot of that moment.
Delete Mood Entries — Swipe left and tap Delete. You'll be asked to confirm before permanent removal.

Dashboard

Wellness Recommendations — Personalized suggestions based on your mood patterns and health data.
Health Metrics — View sleep, steps, and HRV data. Connect Apple Health or enter manually.
Mood Patterns — Quick view of recent mood trends over the past 30 days.
Recent Entries — See your most recent mood logs for today. Tap to view details.
Apple Intelligence — Enhanced insights using on-device AI (iPhone 15 Pro+ or iPad M1+). Falls back to rule-based insights if unavailable — all processing happens on-device for privacy.

Recommendations need at least 3 mood entries. More entries = better insights!

My Journey

Mood Calendar — Tap any day in the calendar to see that day's mood entries. Days with entries are highlighted.
Mood Trend Chart — Tap data points in the Week view to see individual entries. Switch between Week, Month, Year, and All Time to see different trends.

How data points are calculated

Week — individual entries (one point per entry)
Month — daily averages (one point per day)
Year — monthly averages (one point per month)
All Time — quarterly averages (one point per quarter)

Longer timeframes use averages to show overall trends without cluttering the chart with too many data points.

Health Metrics Guide

Connecting Apple Health

Go to Settings → Health Metrics → toggle on Sleep, Steps, or HRV. Grant permissions when prompted.

If Previously Denied

Go to iOS Settings → Privacy & Security → Health → Moodlith → enable the permissions you want to share. Return to Moodlith and toggle the metric on in Settings → Health Metrics.

Sleep Data

Syncs from Apple Health in the morning (typically 8–9 AM). Works with Apple Watch sleep tracking or a third-party sleep app (Fitbit, Garmin, etc.) — as long as that app writes its sleep data into Apple Health, Moodlith will pick it up. You can also enter sleep manually.

Steps

Updates throughout the day. Works with your iPhone's built-in motion tracking, an Apple Watch, or any third-party fitness app that syncs steps into Apple Health. You can also enter steps manually if you don't want to connect Health.

Heart Rate Variability (HRV)

Requires an Apple Watch. HRV helps identify stress and recovery patterns; there's currently no manual entry for HRV since it isn't something you can estimate yourself.

Connecting a third-party tracker (Fitbit, Garmin, Whoop, etc.)

Moodlith doesn't connect to these directly — install the tracker's own app, let it sync into Apple Health (most fitness apps have a "connect to Apple Health" setting), then set the corresponding metric to "Health" in Moodlith. Once it's in Apple Health, Moodlith treats it the same as data from your Apple Watch.

Manual Entry

Enter sleep and steps manually in Settings → Health Metrics if you don't use Apple Health or want to override the synced value.

It may take a day or two for health metrics to start showing after connecting. This is normal — Apple Health needs time to sync data, and some metrics (like sleep) only appear after the first full day of tracking.

Import & Export Data

Import from CSV — Go to Settings → Import Data → select your CSV file. The app will help you map columns to Moodlith fields.

Export Your Data — Go to Settings → Export Data → create a preset. Choose PDF, CSV, or JSON format and select what to include.

Imported data is merged with your existing entries. Duplicate entries (same date/time) may be skipped.

Home Screen Widget

Adding the Widget — Long-press your home screen → tap '+' → search "Moodlith" → choose Small or Medium → Add Widget.
Quick Mood Logging — Tap any emoji in the widget to instantly log your mood. Weather and health metrics are included if enabled.
Widget Features — Small: shows 5 favorite emojis. Medium: shows a 30-day mood trend plus emoji buttons.
Customize Favorites — Go to Settings → Customize Moods → tap the star icon on up to 5 moods. These appear in your widget.

Widget logs are processed when you open the app. You can edit entries later to add notes or tags.

Tips

Log consistently — daily logging improves insights and helps identify patterns over time.
Use tags — tags help identify what activities or situations affect your mood.
Add notes — detailed notes provide context for correlations and better insights.
Review insights regularly — check the AI Insights tab weekly to discover new patterns.
Connect health data — linking Apple Health (or a synced third-party tracker) provides richer insights and better correlations.
Use the widget — add the Moodlith widget to your home screen for one-tap mood logging.

Common Questions

Why isn't my sleep data showing?

Sleep data syncs from Apple Health in the morning (typically 8–9 AM). If you check before then, you'll see "–". Wait until morning or enter sleep manually in Settings → Health Metrics.

How do I connect Apple Health if I previously denied permission?

Go to iOS Settings → Privacy & Security → Health → Moodlith → enable the permissions you want to share (Sleep Analysis, Step Count, Heart Rate Variability). Return to Moodlith → Settings → Health Metrics → toggle on the metrics you want. It may take a day or two for metrics to start showing after connecting.

Why aren't my health metrics showing after connecting?

It may take a day or two for health metrics to start appearing. Apple Health needs time to sync data, and some metrics (like sleep) only appear after the first full day of tracking. Make sure you're actively using Apple Health, Apple Watch, or a connected third-party app to generate data.

Can I use a Fitbit, Garmin, or other fitness tracker instead of an Apple Watch?

Yes, for sleep and steps. Install the tracker's app, enable its sync to Apple Health, then set that metric to "Health" in Moodlith. HRV currently requires an Apple Watch specifically.

I turned off the Apple Health toggle, but it turned itself back on. What's happening?

iOS doesn't let any app fully revoke a Health permission from inside the app — only you can do that, in iOS Settings → Privacy & Security → Health → Moodlith. When you turn the toggle off in Moodlith, the app stops reading your Health data immediately, even though iOS still shows the permission as "granted" in the background. If you want it fully revoked, turn it off from iOS Settings directly.

Why do I see "We're getting to know you"?

You need at least 3 mood entries to generate personalized recommendations. Log a few more moods and recommendations will appear!

How do I import data from another app?

Go to Settings → Import Data → select CSV file. The app will guide you through mapping columns to Moodlith fields.

Where is my data stored?

All data is stored locally on your device. Nothing is sent to external servers — see the Data Usage section below for details.

Can I delete my data?

Yes. Go to Settings → Delete All Data. This permanently removes all mood entries and data. This action cannot be undone.

Why isn't weather showing?

Weather requires location permission. Go to Settings → Personalization → enable Weather Context, then grant location permission when prompted.

Data Usage

What we collect — only what you enable. "Collect" here means stored on your device by the app, not sent to any server. It stays on your device unless you choose to export it:

Feature	What's collected
Mood Entries	Emoji, intensity, tags, notes, timestamp
Sleep Hours	If enabled — from Apple Health or manual entry
Daily Steps	If enabled — from Apple Health or manual entry
Heart Rate Variability	If enabled — from Apple Watch via Apple Health
Weather Data	If enabled — current conditions fetched at log time (not stored ongoing); location used only for that lookup
Apple Intelligence	If enabled — processed entirely on-device
Custom Tags	Tags you create
Imported Data	Anything you import via CSV
App Preferences	Theme, notification settings, metric sources

How we use it

Mood Patterns — identify trends and correlations across your entries.
Personalized Insights — generate recommendations based on your logged data.
Progress Tracking — show your journey over time in charts and calendars.

Privacy protections

Local processing only — all data stays on your device. Nothing is sent to external servers.
No tracking — Moodlith doesn't use analytics SDKs or ad tracking.
Secure by design — health and mood data never leave your device unless you explicitly export it.
Widget data sharing uses Apple's App Groups for local communication between the widget and the app — no data leaves your device.

Important Notes

Data Requirements — minimum 3 mood entries needed for insights. More data = better recommendations.
HealthKit Sleep Data — syncs in the morning (8–9 AM). Early morning checks may show "–" until sync completes.
Privacy & Storage — all data is stored locally. No cloud sync, no tracking. Data never leaves your device unless you export it.
Not Medical Advice — Moodlith is a wellness tracking tool, not a medical device. Insights are for informational purposes only.