MMM-NeedList

A MagicMirror² module that displays a shared household need/shopping list on your mirror. Add items from any device through the built-in admin web interface — they appear on the mirror immediately. When you've picked something up, tap it on the mirror to cross it off; after 60 seconds it's removed and logged to history.

---

Features

• Live updates — items added in the admin appear on the mirror in real time
• Tap to dismiss — click/tap an item on the mirror to start the 60-second removal countdown; tap again to cancel
• Admin web interface — add, edit, complete, or delete items from any phone or browser on your local network
• Share / copy list — tap Share on mobile to send the list to Notes, Google Keep, or any app; on desktop the button reads Copy and puts the list on the clipboard (one item per line)
• History log — every completed item is recorded with a timestamp; browse it in the admin with daily grouping and all-time stats
• No user accounts needed — single shared list for the whole household

---

Screenshot

---

Prerequisites

• MagicMirror² installed and running
• Node.js 18 or later (comes with MagicMirror)

---

Installation

1. Clone the module

cd ~/MagicMirror/modules
git clone https://github.com/johnster000/MMM-NeedList.git

2. Install dependencies

cd MMM-NeedList
npm install

3. Add to your MagicMirror config

Open ~/MagicMirror/config/config.js and add the module entry to the modules array:

{
  module: "MMM-NeedList",
  position: "top_right",   // any MagicMirror region
  config: {
    adminPort: 8082,
    maxWidth: "300px"
  }
},

4. Restart MagicMirror

pm2 restart MagicMirror
# or however you start MagicMirror on your setup

5. Open the admin interface

From any device on your local network, navigate to:

http://<your-mirror-ip>:8082

---

Update

cd ~/MagicMirror/modules/MMM-NeedList
git pull
npm install

---

Configuration Options

Option	Default	Description
adminPort	8082	Port the admin web interface listens on. Must not conflict with other modules (MMM-TaskList uses 8081 by default).
updateFadeSpeed	500	Fade animation duration in milliseconds when the list refreshes.
emptyMessage	"Nothing needed right now."	Text shown on the mirror when the list is empty.
maxWidth	"300px"	Maximum width of the mirror widget. Set this to match your region width in config.js.
title	"Need List"	Label shown above the list on the mirror. Set to "" to hide it.

Full config example

{
  module: "MMM-NeedList",
  position: "top_right",
  config: {
    adminPort: 8082,
    updateFadeSpeed: 500,
    emptyMessage: "All stocked up!",
    maxWidth: "280px",
    title: "Need List"
  }
},

---

Using the Admin Interface

Open http://<mirror-ip>:8082 from any browser on your local network.

Items tab

• Add item — type a need (e.g. "Kleenex", "Paper towels") and press Add. It appears on the mirror immediately.
• ✓ Got it — marks the item as picked up. It's removed from the mirror and added to history.
• ✎ Edit — correct a typo or rename an item.
• ✕ Remove — silently deletes the item without logging it (use this for accidental entries).
• Share / Copy — appears next to the "Current Needs" heading when the list is non-empty. On mobile browsers (Safari iOS, Chrome Android) it opens the native share sheet so you can send the list to any app. On desktop it copies the list to the clipboard. Each item is on its own line.

History tab

Shows stats (all time / this week / today) and a reverse-chronological log of every item that was marked as got, grouped by date. Individual entries can be deleted from the log with the ✕ button.

---

How the Mirror Display Works

• Items are listed in the order they were added.
• Tap an item to cross it out and start a 60-second countdown. After 60 seconds the item is removed and logged as completed.
• Tap the crossed-out item again before the timer fires to cancel the removal (in case of a fat-finger tap).

---

Data Storage

All data is stored locally on the MagicMirror device:

File	Contents
modules/MMM-NeedList/data/items.json	Current open items
modules/MMM-NeedList/data/completed.log	Tab-separated completion log (timestamp\tCOMPLETED\titem text)

The data/ directory is created automatically on first run and is excluded from git.

---

Using Alongside MMM-TaskList

If you run MMM-TaskList on the same mirror, make sure the two modules use different ports:

// MMM-TaskList
{ module: "MMM-TaskList", config: { adminPort: 8081 } }

// MMM-NeedList
{ module: "MMM-NeedList", config: { adminPort: 8082 } }

---

License

MIT