NovelReader
novel-readerOpens on the prose, keeps progress as a character offset, and puts page turn, type size, and paper in a bottom sheet.
Usage
Basic usage
The menu stays hidden, so the page opens on the prose. Next chapter stays at the end of the chapter. Tap the center to summon the catalog and reading settings.
The Ferry Light · Shen Wan
Chapter 1. Night crossing
The river went dark. Shen Wan hung the lamp on the mast.
End of chapter
100%
<NovelReader
className="h-[28rem]"
title="The Ferry Light"
author="Shen Wan"
chapters={chapters}
/>When to Use
Use it for fiction, columns, and manuscripts that should open on the prose. Page turn, type size, line height, measure, and paper live in one settings sheet. The catalog and settings are bottom drawers, not a permanent rail beside the text.
Edit chapters with NovelEditor. Render Markdown with Markdown.
Import
import { NovelReader } from "@hulianui/ui"Props
Inherits HTMLAttributes<HTMLDivElement> except the native title. The root needs a height, such as h-dvh or h-[28rem].
| Name | Type | Default | Description |
|---|---|---|---|
| title | string | — | Book title, shown once above the chapter and again in the summoned top bar |
| author | ReactNode | — | Author |
| chapters | NovelChapter[] | — | Chapters. content is Markdown |
| chapterId | string | — | Controlled current chapter |
| defaultChapterId | string | First chapter | Uncontrolled initial chapter. Stored progress wins |
| onChapterChange | (id: string) => void | — | Called when the chapter changes |
| turn | "scroll" | "cover" | "simulation" | — | Controlled page turn: scroll, cover, or simulation. All three share one forward and back |
| defaultTurn | "scroll" | "cover" | "simulation" | "scroll" | Uncontrolled page turn. Scroll is the default |
| onTurnChange | (turn: NovelTurn) => void | — | Called when the page turn changes |
| mode | "scroll" | "paginated" | — | Legacy alias. paginated means cover and scroll means scroll. turn wins when both are set |
| fontSize | "sm" | "md" | "lg" | "xl" | — | Controlled type size, mapped to text-sm through text-xl |
| defaultFontSize | "sm" | "md" | "lg" | "xl" | "md" | Uncontrolled type size |
| onFontSizeChange | (size: NovelFontSize) => void | — | Called when the type size changes |
| lineHeight | "snug" | "normal" | "relaxed" | "loose" | — | Controlled line height |
| defaultLineHeight | "snug" | "normal" | "relaxed" | "loose" | "relaxed" | Uncontrolled line height |
| onLineHeightChange | (lineHeight: NovelLineHeight) => void | — | Called when the line height changes |
| measure | "narrow" | "normal" | "wide" | — | Controlled measure: max-w-xl, max-w-2xl, or max-w-3xl |
| defaultMeasure | "narrow" | "normal" | "wide" | "normal" | Uncontrolled measure |
| onMeasureChange | (measure: NovelMeasure) => void | — | Called when the measure changes |
| paper | "default" | "day" | "eye" | "night" | "oled" | — | Controlled paper. It wraps the article only; chrome follows the system theme |
| defaultPaper | "default" | "day" | "eye" | "night" | "oled" | "default" | Uncontrolled paper |
| onPaperChange | (paper: NovelPaper) => void | — | Called when the paper changes |
| persistKey | string | — | Stores { chapterId, charOffset } in localStorage. Page index is not stored |
| defaultChromeOpen | boolean | false | Start with the top and bottom bars expanded. Immersive reading keeps them collapsed (tap the middle third to summon). A reading product landing page wants them open, or the first screen is a blank page with no back, no catalog, and no settings |
| onProgressChange | (progress: NovelProgress) => void | — | Progress callback. Progress is only a chapter id and a character offset |
| leading | ReactNode | — | Top-left slot inside the summoned bar, for back and shelf |
| trailing | ReactNode | — | Top-right slot inside the summoned bar |
| articleClassName | string | — | Classes on the body <article>, for a typeface such as a serif. Type size and line height stay on the component's own settings. Do not restyle the article from outside with [&_article] |
NovelChapter
| Name | Type | Default | Description |
|---|---|---|---|
| id | string | — | Stable chapter id |
| title | string | — | Chapter title, without a "Chapter N" prefix |
| content | string | — | Markdown body |
| wordCount | number | Estimated from non-space characters | Display count |
NovelProgress
| Name | Type | Default | Description |
|---|---|---|---|
| chapterId | string | — | Current chapter |
| charOffset | number | — | Offset into the rendered text of the chapter |
Pitfalls
- The root has no height of its own. Without
h-dvhorh-[28rem], the scroller and the page viewport cannot be measured. - Progress is
(chapterId, charOffset), not a page index. Changing type size, line height, or measure changes the page count and would miss the sentence. - Do not wrap the reader in another sticky app bar. The menu is out of flow until summoned.
- Paper means a different sheet, not just a different fill:
dayleans warm (warningat 6%),eyeleans green (successat 11%),nightis a dark base with 5% warmth. All four are mixed from semantic colours, so the paper follows the theme and a dark page never ends up with a snow-white sheet in the middle.oledis the near-black one. The paper paints the whole viewport rather than the<article>; painting the article leaves a sheet that stops dead at the last line.data-themerides the viewport too, so chrome still follows the page tokens while the paper wraps the prose. - The reader has no annotation or chapter-comment layer. Do not cover it with a splash, an app install prompt, a promotion, or a task modal.
- The center hotspot only toggles the menu. Put back and shelf in
leadingortrailing. - Catalog and settings are bottom drawers. Do not pin a gear to the left edge. The settings backdrop stays transparent. The panel sets an inline
color-mix(in srgb, var(--color-surface) 80%, transparent)and does not usebackdrop-blur.bg-surface/80alone is emitted as opaquevar(--color-surface)first, so a failedcolor-mix(in lab)test leaves a solid light panel and hides the current sentence. - Chapter buttons say previous chapter and next chapter. Do not reuse Pagination, whose labels mean previous page and next page.
- Do not pin a page-level header or footer for previous and next chapter. Previous chapter stays at the chapter start and is omitted on the first chapter. Next chapter stays at the chapter end, in the text flow, including while the menu is hidden, and is omitted on the last chapter. Chapter controls in the top and bottom bars hide with the menu.
- Set the body typeface with
articleClassName. Do not restyle the article from outside with[&_article]. Body Markdown follows the reader's type size and line height.
Related
NovelEditor · Markdown · Drawer · Empty