{"id":49256590,"url":"https://github.com/anthonygress/zen_ui.koplugin","last_synced_at":"2026-05-24T22:02:22.411Z","repository":{"id":353284516,"uuid":"1194031944","full_name":"AnthonyGress/zen_ui.koplugin","owner":"AnthonyGress","description":"A clean, minimal UI for KOReader. Enjoy reading on e-readers with a simple and intuitive interface","archived":false,"fork":false,"pushed_at":"2026-05-22T03:25:58.000Z","size":7241,"stargazers_count":178,"open_issues_count":31,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-22T08:53:48.772Z","etag":null,"topics":["android","boox","desktop","eink-devices","ereader","kindle","kobo","koreader","koreader-plugin","lua","pocketbook"],"latest_commit_sha":null,"homepage":"https://anthonygress.github.io/zen_ui.koplugin/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AnthonyGress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["Anthonygress"],"buy_me_a_coffee":"anthonygress"}},"created_at":"2026-03-27T21:01:17.000Z","updated_at":"2026-05-22T02:33:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AnthonyGress/zen_ui.koplugin","commit_stats":null,"previous_names":["anthonygress/zen_ui.koplugin"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/AnthonyGress/zen_ui.koplugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnthonyGress%2Fzen_ui.koplugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnthonyGress%2Fzen_ui.koplugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnthonyGress%2Fzen_ui.koplugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnthonyGress%2Fzen_ui.koplugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AnthonyGress","download_url":"https://codeload.github.com/AnthonyGress/zen_ui.koplugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnthonyGress%2Fzen_ui.koplugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33452033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","boox","desktop","eink-devices","ereader","kindle","kobo","koreader","koreader-plugin","lua","pocketbook"],"created_at":"2026-04-25T04:07:58.985Z","updated_at":"2026-05-24T22:02:22.371Z","avatar_url":"https://github.com/AnthonyGress.png","language":"Lua","funding_links":["https://github.com/sponsors/Anthonygress","https://buymeacoffee.com/anthonygress"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./icons/zen_ui_light.svg\" /\u003e\n    \u003cimg width=\"300\" src=\"./icons/zen_ui.svg\" alt=\"Zen UI logo\" /\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003ch1 align=\"center\"\u003eZen UI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eA clean, minimal UI for KOReader. \u003c/p\u003e\n\n## Philosophy\n\nZen UI is built around the simple idea that **less is more.** Everything in Zen UI was designed either to remove clutter or add clear value. The interface stays fast, light, and focused on making reading more enjoyable.\n\nThroughout development, three things were non-negotiable: **performance**, **stability**, and **ease of use**. Every feature was tuned for battery efficiency and responsiveness. \n\n## Speed \u0026 Performance\n\nZen UI is built to be lightweight and efficient. With libraries containing thousands of books, there are no dramatic changes in speed, responsiveness, or resource usage. Patches are strategically injected and only loaded when needed. Zen UI maintains consistent performance without taxing your device's battery or memory, regardless of the size of your library.\n\n## Features\n\n### Quick Settings Panel\nA swipe-down menu accessible anywhere containing all the controls you frequently use — brightness, warmth, WiFi, night mode, sleep, rotation, and more. Fully configurable.\n\n\u003cimg src=\"./images/quickstart/onboarding/quicksettings.png\" width=\"500\" alt=\"Quick Settings\"\u003e\n\n### Library\n\n\u003cimg src=\"./images/quickstart/onboarding/library_covers_full.png\" width=\"350\" height=\"auto\" alt=\"Library Covers\"\u003e\n      \n\u003cimg src=\"./images/quickstart/onboarding/library_list_full.png\" width=\"350\" height=\"auto\" alt=\"Library List\"\u003e\n\n- Clean mosaic and list view options maximizing the size of your book covers with many options\n- Book cover gallery for folder thumbnails\n- Configurable sorting, items per page, and landscape/portrait layout\n- A streamlined context menu in the file browser. Tap and hold to quickly access details, fullscreen cover art, read status and more.\n\n\u003cimg src=\"./images/quickstart/onboarding/context_menu.png\" width=\"350\" height=\"auto\" alt=\"Context Menu\"\u003e\n\u003cimg src=\"./images/quickstart/onboarding/library_context.png\" width=\"350\" height=\"auto\" alt=\"Library Context\"\u003e\n\n### Bottom Navigation Bar\nA clean, tab-based navigation bar at the bottom of the library. Configurable tabs (Library, Manga, Favorites, Authors, History, Collections, and more), with optional labels, custom icons, and sortable layout.\n\n\u003cimg src=\"./images/quickstart/onboarding/navbar.png\" width=\"500\" alt=\"Navigation Bar\"\u003e\n\n### Zen Mode\n\nStrips down the default KOReader interfaces to their bare essentials. - Hides all the default menus from KOReader leaving only a single unified Zen UI settings tab.\n\n\u003cimg src=\"./images/quickstart/onboarding/zen_mode.png\" width=\"175\" alt=\"Zen Mode\"\u003e\n\n### Lockdown Mode\n\nCreates a more locked-down sandbox for distraction-free reading. Lockdown Mode is designed to keep the device focused on the core flow: browse books and read books. This mode is great for very old or very young readers who shouldn't be burdened by any settings or unnecessary options.\n\n- Restricts access to settings and configuration changes\n- Optionally magnify the UI for a larger, simpler view \n- Keeps the experience simple, and reading-first\n\n\u003cimg src=\"./images/quickstart/onboarding/lockdown_mode.png\" width=\"175\" alt=\"Lockdown Mode\"\u003e\n\n\n### Custom Status Bars\nA minimal status bar in the reader and a more detailed one in the library. Show only what you want: time, battery, disk space, custom text — all optional and individually toggled.\n\n\u003cimg src=\"./images/quickstart/onboarding/status_bar.png\" width=\"500\" alt=\"Status Bar\"\u003e\n\n### Reader Improvements\n- Custom page browser (similar to Kindle's) for scrubbing through pages, searching the book, quickly changing the font size.\n- Disable bottom menu, prevent unwanted changes to font size.\n- Margin gaurd preventing accidentally gestures while holding the edge of the device by it's touchscreen.\n- Pick from a hadful of predesigned reader progress bars or create and save your own. Switch presets with a single tap.\n\n\u003cimg src=\"./images/quickstart/onboarding/reader.png\" width=\"500\" alt=\"Reader\"\u003e\n\n### Automated Lighting Schedules\nThree independent scheduling systems replace KOReader's limited auto night mode:\n\n- **Night Mode Schedule** — Automatically turn night mode on/off at specified times each day\n- **Brightness Schedule** — Schedule brightness levels for night/day\n- **Warmth Schedule** — Schedule screen warmth for night/day\n\nEach schedule works individually or together. This granular approach lets you tailor the lighting exactly to your preferences.\n\n### OPDS Plugin Theming\nThe OPDS plugin respects all your Zen UI library styling settings — creating a unified visual experience across both your local library and online catalogs.\n\n- Mosaic, cover grid, and list view modes from your library settings\n- Rounded corners on covers, if enabled\n- Default catalog with 1 click access from quick settings\n\nBrowse your favorite OPDS sources with the same clean, consistent interface you've customized for your local collection.\n\n## Unified Settings \n- Pulled the most important settings into a single, more streamlined settings tab\n- Settings are grouped by feature area (Library, Navbar, Quick Settings, Status Bar, Reader).\n- Most features can be toggled independently, some reasonable defaults have been selected.\n- Update Zen UI directly from settings without ever leaving KOReader or plugging in to a computer.\n\n\u003cimg src=\"./images/quickstart/onboarding/zen_ui_settings.png\" width=\"500\" alt=\"Zen UI Settings\"\u003e\n\n## Prerequistes\n\n- KOReader must be installed first in order to use Zen UI. [Install KOReader](https://github.com/koreader/koreader#installation)\n\n## Installation\n\n1. Go to the [Releases](https://github.com/AnthonyGress/zen_ui.koplugin/releases) page and download `zen_ui.koplugin.zip` from the latest release.\n2. Unzip the archive. You should have a **folder** named `zen_ui.koplugin`.\n3. Copy the `zen_ui.koplugin` **folder** into the KOReader plugins directory for your device: See table below\n      - Make sure you are copying the unzipped **folder** and **not the .zip** file itself\n4. Restart KOReader. Zen UI will load automatically\n      - If you don't see Zen UI load, manually enable the plugin in Tools \u003e More tools \u003e Plugin management \u003e Zen UI\n\u003e The final path should look like: `.../plugins/zen_ui.koplugin/main.lua`  \n\n\n| Device | Plugins directory |\n|--------|-------------------|\n| **Kobo** | `/mnt/onboard/.adds/koreader/plugins/` |\n| **Kindle** | `/mnt/base-us/koreader/plugins/` |\n| **PocketBook** | `/mnt/ext1/applications/koreader/plugins/` |\n| **Android** | `sdcard/koreader/plugins/` |\n| **Desktop (Linux/macOS)** | `/koreader/plugins/` |\n\n## Migrating from Project Title\n\nIf you previously used [Project Title](https://github.com/joshuacant/ProjectTitle), you must disable or remove it before using Zen UI. Both plugins patch the Cover Browser, and having both active at the same time will cause conflicts.\n\nChoose one of the following:\n\n- **Remove it** — Delete the `projecttitle.koplugin` folder from your KOReader plugins directory.\n- **Disable it** — Rename the folder to `projecttitle.koplugin.disabled`. KOReader will ignore it on next launch.\n\nAfter disabling or removing Project Title, restart KOReader and Zen UI will load cleanly.\n\n## Localization\n\nZen UI is currently translated into:\n\n| Locale | Language |\n|--------|----------|\n| `en` | English |\n| `it` | Italian |\n| `es` | Spanish |\n| `fr` | French |\n| `nl` | Dutch |\n| `bg` | Bulgarian |\n| `pt_BR` | Brazilian Portuguese |\n| `pt_PT` | European Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `zh_CN` | Simplified Chinese |\n| `zh_TW` | Traditional Chinese |\n\nIf you find any issues or corrections to the translations, please feel free to contribute.\n\nTo contribute a translation or fix an existing one, see [locales/README.md](locales/README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Credits\n\nZen UI is original work, but it wouldn't exist without the broader KOReader community. Several open source projects provided components, inspiration, reference implementations, or code that was adapted and built upon:\n\n- **[joshuacant/ProjectTitle](https://github.com/joshuacant/ProjectTitle)** — The plugin that started it all for me. This was my first experience with KOReader plugins and an alternative UI.\n- **[qewer33/koreader-patches](https://github.com/qewer33/koreader-patches)** — The bottom navbar and quick settings components. Additional patch approaches and ideas, particularly around UI customization.\n- **[sebdelsol/KOReader.patches](https://github.com/sebdelsol/KOReader.patches)** — Patches and UI techniques that informed several of Zen UI's features.\n- **[doctorhetfield-cmd/simpleui.koplugin](https://github.com/doctorhetfield-cmd/simpleui.koplugin)** — A fellow KOReader UI plugin that served as an inspiration as well as a model for how to apply language translations throughout the plugin.\n- **[kristianpennacchia/zzz-readermenuredesign.koplugin](https://github.com/kristianpennacchia/zzz-readermenuredesign.koplugin)** — Inspiration for the reader search menu redesign\n\nThank you to everyone who published their KOReader work openly.\n\n## Contributing\n\nBug reports, feature requests, translations, and code contributions are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\nPlease follow these guidelines:\n\n- **One feature per PR** - Keep pull requests focused on a single feature or fix\n- **PR to dev branch** - Submit PRs to the `dev` branch for testing/review.\n- **Review AI-generated code** - If using AI tools, all code must be thoroughly reviewed and tested before submitting (this should happen anyway but even moreso for AI generated code)\n- **Maintain consistency** - New code must align with the project's existing style, theme, and overall user experience\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for how to report vulnerabilities.\n\n## License\n\n[GPL-3.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonygress%2Fzen_ui.koplugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthonygress%2Fzen_ui.koplugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonygress%2Fzen_ui.koplugin/lists"}