Mosaic guide: grids, free placement and HTML widgets

Mosaic lets you lay out your Home Screen your way: custom grids for the Home Screen, Dock and folders, apps placed anywhere on a page, and HTML widgets on the Lock and Home Screens. You do most of it from a small edit bar on the Home Screen, and you can save whole Home pages to bring back later.

Before you start

• A rootless jailbroken iPhone on iOS 15, 16 or 17, such as Dopamine. Not sure which jailbreak fits your iPhone? Use the jailbreak finder.
• Sileo or Zebra with the CarterWare repo added. See Install CarterWare tweaks. Sileo installs what Mosaic needs (ElleKit or Substrate, and PreferenceLoader) for you.
• Mosaic was tested end to end on iOS 16.3.1 and iOS 17.1. iOS 15 is supported but hasn't been retested on the newest version.
• Only one layout tweak should control your icons. Mosaic pauses its grid when it finds Atria, Boxy, Griddy, FreeformGrid, HomePlus, Iconoclasm or similar tweaks, so turn those off first.
• Mosaic replaces HomeClean. HomeClean's page vault lives on as Saved Pages, and your package manager removes HomeClean when you install Mosaic.
• Mosaic costs $3.99 one-time, or it's included with Tweak Pass ($10/month). See Buying and restoring.

Set it up

1. Buy and install Mosaic from the CarterWare repo, then respring (restart the Home Screen) when asked.
2. Open Settings → Mosaic and check that Enabled and Layout Hooks are on.
3. Tap Check Conflicting Tweaks. If it names another layout tweak, turn it off or uninstall it, then respring.
4. On the Home Screen, touch and hold any app on a Home page (not the Dock or a folder) and choose Mosaic ("Layout, Widgets & Pages"). Touching and holding an empty spot works too.
5. It's working when your apps jiggle, the app you held has a white ring, and a bar with Add, Position, Size, Opacity and More sits above the Dock.
6. Tap More → Quick Layout… and move Columns to 5. Your apps reflow right away. Tap Done twice to finish.

Common tasks

Edit the Home Screen with the Mosaic bar

1. Touch and hold an app and choose Mosaic, or touch and hold an empty spot on the Home Screen.
2. Tap an app or a Mosaic widget to select it. A white ring shows what's selected.
3. Use the buttons on the bar (below), then tap Done on the Home Screen.

• Add opens the widget picker.
• Position opens Horizontal and Vertical sliders for the selected app or widget; dragging still works while it's open.
• Size resizes the selected widget. When an app is selected it reads Reset and puts the app back in its grid spot.
• Opacity fades the selected widget.
• More holds Quick Layout, Widgets, Icons, Pages and Mosaic Settings.

Mosaic pauses page swiping while you edit, so a drag never flips the page. To work on another page, tap Done, swipe to it, and start editing again.

Change the grid: columns, rows, spacing and icon size

1. While editing, tap More → Quick Layout….
2. Pick Home Screen, Dock or Folders at the top.
3. Drag Columns, Rows, Horizontal Spacing, Vertical Spacing, Push Down, Side Margins or Icon Size. Changes show live.
4. Tap Done.

The Home grid and folder sliders are also in Settings → Mosaic. Dock settings are only in Quick Layout; the Dock always has one row, and Home spacing never moves it.

Give one Home page its own grid

1. Swipe to the page, then start editing.
2. Tap More → Quick Layout…, choose Home Screen, then This Page (it shows the page number).
3. Change the sliders. Only that page changes; the rest keep the All Pages layout.
4. To undo it, open Quick Layout on that page and tap Use All Pages Layout on Page (with the number). Settings → Mosaic → Clear Per-Page Overrides undoes it on every page.

Put an icon anywhere on the Home Screen

1. Start editing and check More → Icons → Free Placement is on. It turns itself on the first time you edit with Mosaic, unless you've switched it off.
2. Drag an app on a Home page and let go where you want it. It stays there after a respring.
3. Snap to Grid pulls apps toward grid spots, and Snap to Align shows blue guide lines when apps line up. Both are in More → Icons.
4. For exact placement, select the app and tap Position.

To put an app back in the grid, select it and tap Reset. For a whole page, use More → Icons → Reset Icon Positions on This Page…. Positions are saved per page. The Dock and folders always use a grid.

Add an HTML widget to the Lock Screen or Home Screen

1. While editing, tap Add.
2. Pick a widget. Mosaic comes with SampleClock, SampleBanner and a few free Evelyn widgets, grouped under Evelyn, Installed and Samples.
3. Choose Set as Lock Screen Background or Set as Home Screen Background.

Settings → Mosaic → HTML Widgets has Background, Foreground and Extra Layer slots for each screen, so you can stack up to three.

Install Xen HTML or ZenHTML widget packs

1. In Filza, open /var/jb/Library/Mosaic/Widgets/Universal.
2. Copy the widget's folder there. The folder name is the name you'll see in the pickers.
3. Tap Add on the Home Screen (it rescans every time), or tap Settings → Mosaic → Reload Widget List.

A widget folder needs an HTML file plus the files it uses (CSS, scripts, images). Mosaic opens index.html first, then LockBackground.html, Wallpaper.html, Background.html or Foreground.html, otherwise the first .html file. An optional config.json can set touch (true lets you tap the widget; otherwise taps pass through), opacity (0–1 or 0–100), refresh (seconds between data updates), hideClock (hides the stock Lock Screen clock) and frame (x, y, width, height; 1 or less means a share of the screen).

Widgets in the classic Xen HTML folders under /var/mobile/Library show up too. If Sileo refuses an old widget package, open the .deb in Filza and copy the folder holding the .html file into the Universal folder.

Put a widget on a Home page

1. Swipe to the page and start editing.
2. Tap Add, pick a widget, and choose Add to This Page. It scrolls with your apps instead of sitting on the wallpaper.
3. Drag it into place, or select it and use Position, Size (Small, Medium, Large, Full Width, or Width and Height sliders) and Opacity (down to 20%).
4. With it selected, More also offers Lock Widget (stops it moving), Replace Widget… (keeps its size, position, lock and opacity) and Delete Widget.

More → Widgets has Center & Lock All, Remove a Widget and Clear Widgets on This Page….

Save a Home page and put it back later

1. Swipe to the page and start editing.
2. Tap More → Pages → Save This Page.
3. Later, tap More → Pages → Saved Pages…, tap the saved page, then Restore to This Page.

Restoring moves the saved apps onto the page you're on, adding a page if it's full. Apps in the Dock or folders stay put, and deleted apps are skipped. Swipe left on a saved page to delete it.

More → Pages → Remove Apps from This Page… empties a page into the App Library; save it first if you want it back. The same tools are in Settings → Mosaic → Saved Pages.

Save, export or load a layout

1. Tap Settings → Mosaic → Save Current Layout. It's named "Preset-" plus a number and selected in Load Layout.
2. To share it, tap Export Layout Document. Mosaic writes a .mosaiclayout file to /var/jb/Library/Mosaic/Layouts and shows the path.
3. To import one, copy a .mosaiclayout file into that folder with Filza.
4. Pick a layout in Load Layout, then tap Apply Selected Layout.

A layout holds your Home, Dock and folder grids, per-page grids, icon size and Cosmetics switches. It doesn't include where apps are, free-placed positions or widgets; use Saved Pages for apps.

Hide icon labels, the Dock or the page dots

1. Open Settings → Mosaic.
2. Under Cosmetics, turn on Hide Icon Labels, Hide Dock or Hide Page Dots. They apply right away.

On iOS 16 and later, Hide Page Dots also hides the Search button in their place; swipe down on the Home Screen to search. Hide Dock also hides the iPad-style floating Dock some tweaks turn on.

Go back to the stock layout

1. In Settings → Mosaic, tap Restore Stock Layout, then Restore. Grids, icon size and Cosmetics go back to stock, per-page grids are removed, and Layout Hooks turns off.
2. Tap Reset All Icon Positions to put free-placed apps back in the grid.
3. To remove widgets too, tap Remove All Wallpaper Widgets and Remove ALL Inline Widgets (All Pages).
4. Tap Apply Layout (Respring).

To pause Mosaic without losing your work, turn off Enabled instead. After a restore, turn Layout Hooks back on to use Mosaic grids again.

Settings explained

Everything below is in Settings → Mosaic. The first footer also shows how many widgets Mosaic found.

Saved Pages…

Lists your saved Home pages. Save Current Home Page saves the Home page you last viewed. Tap a saved page for Restore to Home Screen (back onto the page you last viewed) or Delete, or swipe left to delete.

Troubleshooting

My grid changes do nothing

Mosaic pauses its grid when another layout tweak is installed (Atria, Boxy, Griddy, FreeformGrid, HomePlus, Iconoclasm, Gridiculous, Cubex, DockController and similar), and it counts SnowBoard too. If More → Quick Layout… says Layout Hooks are off, check Settings → Mosaic → Layout Hooks is on, tap Check Conflicting Tweaks, then remove the other tweak and respring.

Force Layout Hooks makes Mosaic apply its grid anyway. Two tweaks moving the same icons can crash the Home Screen into Safe Mode, so only use it if you accept that risk. Never use Atria's or Griddy's editor alongside Mosaic's Free Placement.

A full-screen widget is stuck and I can't remove it

Tap Settings → Mosaic → Remove All Wallpaper Widgets, then Remove. Every Lock and Home slot goes back to (None). If it's still showing, tap Respring. For a widget stuck on top of your apps, use Remove ALL Inline Widgets (All Pages).

The widget picker is empty or my new widget isn't listed

Make sure the widget folder sits directly inside /var/jb/Library/Mosaic/Widgets/Universal with an .html file in it, not one folder deeper. Tap Reload Widget List, and if the Settings pickers still miss it, leave Settings → Mosaic and open it again. If even SampleClock is missing, reinstall Mosaic.

A widget says "Widget failed to load"

Its HTML didn't load. Tap Reload Widget List, then try SampleClock to check widgets work at all. Third-party packs vary, and some old ones don't work on iOS 16 or 17. If SampleClock fails too, report a bug.

A new widget covers my top row of apps

New page widgets start near the top. Drag it down, or select it and use Position or Size.

Settings changes don't stick

Most changes apply live, but big grid changes can look half-applied until a reload. Tap Settings → Mosaic → Apply Layout (Respring).

My iPhone went into Safe Mode

Respring out of Safe Mode. If it happens again, turn off Force Layout Hooks and remove any other layout tweak. If it still happens, uninstall Mosaic in Sileo; your saved pages and layouts stay on the phone. See Troubleshooting for Safe Mode basics, and tell us with Report a Bug.

Questions

Does Mosaic replace HomeClean?

Yes. HomeClean is retired, and its page vault is now Saved Pages in Mosaic: save a Home page, restore it later, or clear a page into the App Library. Installing Mosaic removes HomeClean.

Does Mosaic work with Xen HTML widgets?

Yes. Mosaic runs Xen HTML and ZenHTML widget folders itself, so you don't need Xen HTML installed, and it supplies the battery, time, weather, music, calendar and reminder data those widgets expect. Packs vary, so start with SampleClock.

Can I use Mosaic with Boxy, Atria or Griddy?

Not at the same time. Mosaic pauses its grid when it finds them, because two layout editors fight over your icons.

Will Saved Pages or Remove Apps delete my apps?

No. Saving, restoring and Remove Apps from This Page… only move icons. Removed apps stay installed and in the App Library.

What happens to my Home Screen if I uninstall Mosaic?

After the respring, your Home Screen goes back to the stock grid. Your apps stay installed, and your saved pages, layouts and added widgets stay on your iPhone in case you reinstall.

Which iOS versions does Mosaic support?

iOS 15, 16 and 17 on a rootless jailbreak such as Dopamine. It was tested end to end on iOS 16.3.1 and iOS 17.1; iOS 15 is supported but hasn't been retested on the newest version.

How much does Mosaic cost?

$3.99 one-time, or included with CarterWare Tweak Pass at $10/month while your Pass is active. See Buying and restoring.