SimpleUI for KOReader

A clean, distraction-free UI plugin for KOReader that transforms your reading experience. SimpleUI adds a dedicated Home Screen, a customisable bottom navigation bar, a top status bar, and a reworked library title bar, giving you instant access to your library, history, collections, and reading stats without navigating through nested menus.

Features

Home Screen

The centrepiece of SimpleUI. A home screen that gives you everything at a glance:

• Clock & Date — a large, readable clock with full date display
• Currently Reading — your active book with cover art, title, author, progress bar, percentage read, and estimated time left
• Recent Books — a row of up to 5 recent books with cover thumbnails and progress indicators; tap any to resume reading
• Collections — your KOReader collections displayed as tappable cover cards, right on the home screen
• Reading Goals — visual progress tracker for your annual and daily reading goals, including physical books read
• Reading Stats — compact stat cards showing today's reading time, pages, streaks, and all-time totals
• Quick Actions — up to 3 customisable rows of shortcut buttons (Library, History, Wi-Fi toggle, Brightness, Stats, and more)
• New Books — a row of up to 5 recently added books sorted by file date; unread books are labelled "New" and started books show their read percentage; opt-in via Arrange Modules
• Quote of the Day — optional literary header, randomly picked from a curated list of 100+ quotes; can also show your own highlights
• Module ordering — rearrange Home Screen modules in any order to match your workflow
• Per-module scaling — resize each module independently, or lock all scales together for uniform adjustments
• Start with Home Screen — set the Home Screen as the first screen KOReader opens every time you pick up your device

Bottom Navigation Bar

A persistent tab bar at the bottom of the screen for one-tap navigation:

• Up to 5 fully customisable tabs: Library, History, Collections, Favourites, Continue Reading, Home Screen, Wi-Fi Toggle, Brightness, Stats, Bookmark Browser, and custom folder or collection shortcuts
• 3 display modes: icons only, text only, or icons + text
• Navpager mode — replaces the pagination bar with Prev/Next arrows at the edges of the bottom bar; arrows dim when there is no previous or next page
• Hold anywhere on the bar to instantly open navigation settings

Top Status Bar

A slim status bar always visible at the top of the screen:

• Displays clock, battery level, Wi-Fi status, frontlight brightness, disk usage, and RAM all configurable
• Each item can be placed on the left or right side independently

Custom Title Bar

A reworked title bar for the Library, History, Collections, and other full-screen views:

• Back button — replaces KOReader's default navigation with a cleaner chevron; hides automatically at the root folder, and also hides when the Library's Lock Home Folder setting is active and you are already at the home folder
• Search button — quick access to file search, compacts into the freed slot when the back button is hidden
• Menu button — opens the KOReader main menu
• Page number in title — shows "Page X of Y" in the subtitle when browsing multi-page views (enabled automatically by Navpager)
• Button size — three sizes (Compact, Default, Large) for the title bar buttons
• Separate layouts — Library buttons and sub-page buttons (History, Collections, etc.) can be configured independently

Folder Covers

Custom cover art for folders in the Library mosaic view:

• Automatically uses the first book cover found inside a folder
• Supports a *`.cover.` image file** placed manually in the folder for full control
• Long-press any folder and tap Set folder cover… to pick a specific book's cover as the folder's cover, only visible when Folder Covers is enabled
• Optional folder name label with configurable position (top, centre, bottom) and style (solid or transparent background)
• Optional item count badge with configurable position
• Hide selection underline for a cleaner look

Quick Actions

Shortcut buttons configurable both on the Home Screen and in the bottom bar:

• Assign any action to a custom folder, collection, or KOReader plugin
• Quick Wi-Fi toggle and frontlight control
• Power menu (Restart, Quit) accessible as a tab
• Bookmark Browser — browse your highlights and bookmarks across all books

Settings

All features are accessible via Menu → Tools → SimpleUI

Installation

1. Download this repository as a ZIP — click Code → Download ZIP
2. Extract the folder and confirm it is named simpleui.koplugin
3. Copy the folder to the plugins/ directory on your KOReader device:
   • Kobo: /.adds/koreader/plugins
   • Kindle: /koreader/plugins
   • Android: koreader/plugins at the root of onboard storage.
4. Restart KOReader
5. Go to Menu → Tools → SimpleUI to enable and configure the plugin

Tip: After enabling the plugin, tap the Home Screen tab in the bottom bar to open your new home screen.

Tip: To make the Home Screen your default start screen, go to Menu → Tools → SimpleUI → Home Screen → Start with Home Screen. From then on, KOReader opens directly to your home screen every time you turn on your device.

🌍 Translations

SimpleUI has full translation support. The UI language is detected automatically from your KOReader language setting — no configuration needed.

Included languages

⚠️ These files contain syntax errors and may not load correctly. Contributions to fix them are welcome.

Adding a new language

All 768 strings in the plugin are translatable. To add a new language:

1. Copy locale/simpleui.pot to locale/<lang>.po, using the standard locale code for your language (examples: de, fr, it, ja)
2. Open the file in any text editor or a dedicated PO editor such as Poedit
3. For each entry, fill in the msgstr field with your translation:

msgid "Currently Reading"
msgstr "Aktuell gelesen"

4. Save the file inside the locale/ folder — no code changes needed
5. Restart KOReader; the plugin picks up the new language automatically

The plugin first tries an exact match for the locale code (e.g. pt_PT.po), then falls back to the language prefix (e.g. pt.po), then falls back to English.

Notes for translators

• Placeholders like %d, %s, and %% must be kept in your translation exactly as they appear in the msgid — you can reorder them if your language requires it, but not remove them
• \n is a line break — keep it in the same position
• Never modify the msgid line — only edit msgstr
• If a msgstr is left empty (""), the English original is shown as a fallback
• Submitting your translation as a Pull Request is very welcome — see CONTRIBUTING.md

🔧 Customisation

Custom Quote of the Day

You can supply your own quotes by placing a .lua file in the custom quotes folder on your device:

<KOReader settings dir>/simpleui/custom_quotes/

(<KOReader settings dir> is typically /mnt/onboard/.adds/koreader/settings on Kobo or /mnt/us/koreader/settings on Kindle.)

The file must return a table of entries in this format:

return {
    { q = "Quote text.", a = "Author Name", b = "Book Title (optional)" },
    { q = "Another quote.", a = "Another Author" },
}

Once the file is in place, go to Menu → Tools → SimpleUI → Home Screen → Quote of the Day → Source → Custom and select your file. Changes take effect the next time the Home Screen is opened.

The custom_quotes/ folder is created automatically on first run and is never touched by plugin updates.

To add, remove or edit the built-in quote pool instead, open desktop_modules/quotes.lua inside the plugin folder and follow the same format.

Custom Quick-Action Icons

You can use your own SVG icons for custom quick-action buttons. Place .svg files in the custom icons folder:

<KOReader settings dir>/simpleui/custom_icons/

They will appear in the icon picker when creating or editing a custom quick action (Menu → Tools → SimpleUI → Quick Actions → Edit → Icon).

The custom_icons/ folder is created automatically on first run and is never touched by plugin updates.

Icon Packs

An icon pack lets you replace multiple SimpleUI icons at once — titlebar buttons, pagination chevrons, navigation tab icons, and quick-action icons — with a single tap.

Where to place packs

<KOReader settings dir>/simpleui/sui_icons/packs/

A pack can be either:

• A subfolder containing icon files with the correct names (see below).
• A .zip file containing those same files, either flat or inside a single root folder.

You can place packs there manually, or use Style → Icons → Icon Packs → Install pack from ZIP… to browse to a .zip directly on your device.

The packs/ folder is created automatically on first run and is never touched by plugin updates.

Applying a pack

Go to Menu → Tools → SimpleUI → Style → Icons → Icon Packs and tap the pack you want. Icons are applied immediately to the live UI — no restart needed.

Packs are additive and partial: only the slots covered by the pack are changed. Slots not included in a pack keep their current value (custom or default). To revert everything afterwards, use Style → Icons → System Icons → Reset All System Icons.

File-name conventions

Every file in the pack root must be an .svg or .png. The filename (without extension) determines which icon slot it fills:

SimpleUI titlebar buttons

Browse-by buttons (Library titlebar)

Native pagination chevrons

Navpager arrows (Bottom Bar)

Quick-action icons (prefix sui_action_)

Quick Actions Defaults

Folder Covers

Files with names that do not match any of the above are silently ignored.

Optional manifest (pack.lua)

A pack can include a pack.lua file in its root to provide metadata and override the default filename conventions:

return {
    name        = "Night Owl",          -- display name in the menu (default: folder name)
    author      = "your-name",
    version     = "1.0",
    description = "Dark, rounded icons",

    -- Optional: map a slot ID to an alternative filename inside the pack.
    -- Useful if you want filenames that differ from the convention above.
    map = {
        sui_menu    = "hamburger.svg",
        sui_pager_prev = "arrow-left.svg",
    },
}

If pack.lua is absent, the pack name shown in the menu is the folder name (or the zip stem).

Typical pack structure

NightOwl/                       ← pack name (or NightOwl.zip)
  pack.lua                      ← optional manifest
  sui_menu.svg
  sui_search.svg
  sui_back.svg
  sui_browse_normal.svg
  sui_browse_author.svg
  sui_browse_series.svg
  sui_browse_tags.svg
  sui_pager_prev.svg
  sui_pager_next.svg
  sui_pager_first.svg
  sui_pager_last.svg
  sui_navpager_prev.svg
  sui_navpager_next.svg
  sui_action_library.svg
  sui_action_collections.svg
  sui_action_history.svg
  sui_action_continue.svg
  sui_action_frontlight.svg
  sui_action_night_mode.svg
  sui_action_power.svg
  sui_action_settings.svg

All files are optional — a valid pack can contain as few as one icon.

Notes for pack authors

• Use .svg for best results; KOReader renders SVGs at any resolution. .png files work but may look blurry on high-DPI screens.
• Icon paths are stored as absolute paths in settings. If you move or rename the pack folder after applying it, the icons will break until you re-apply the pack. Zip-installed packs are extracted to packs/ and are therefore stable.
• To share a pack, zip the folder (NightOwl/) and distribute the .zip.

Contributing

Contributions are welcome — bug fixes, new features, translations, and documentation improvements. See CONTRIBUTING.md for how to get started.

To report a bug, open an Issue and include your KOReader version and device model.

📄 License

MIT — see LICENSE for details.