react-comic-viewer

A comic/manga viewer component for React.

Demo

https://react-comic-viewer.kkweb.io

Features

• RTL (right-to-left) and LTR support for manga/comic reading
• Responsive single/double page view
• Fullscreen mode
• Swipe navigation on touch devices
• Keyboard navigation (Arrow keys, Escape)
• Double-tap to zoom
• Tap to show/hide UI
• Thumbnail navigation
• Loading indicator
• Page preloading
• TypeScript support

Requirements

• React 18 or later

Installation

npm install react-comic-viewer

Usage

import { ComicViewer } from "react-comic-viewer";
import "react-comic-viewer/styles.css";

function App() {
  return (
    <ComicViewer pages={["page1.jpg", "page2.jpg", "page3.jpg", "page4.jpg"]} />
  );
}

export default App;

Props

| Prop | Type | Default | Description | | ------------------- | ---------------------------------------------------------- | ------- | ---------------------------------------------------- | | pages | Array<string \| ReactNode \| PageRenderer> | - | Required. Image URLs, React nodes, or renderers | | direction | "rtl" \| "ltr" | "rtl" | Reading direction | | currentPage | number | - | Controls the current page. See Controlled mode | | isExpansion | boolean | - | Controls the expansion state. See Controlled mode | | initialCurrentPage | number | 0 | Initial page index, used when uncontrolled | | initialIsExpansion | boolean | false | Initial expansion state, used when uncontrolled | | showPageIndicator | boolean | false | Show current page indicator | | switchingRatio | number | 1 | Aspect ratio threshold for single/double page switch | | onChangeCurrentPage | (currentPage: number) => void | - | Callback when page changes | | onChangeExpansion | (isExpansion: boolean) => void | - | Callback when expansion state changes | | onTryMoveNextPage | (nextPage: number) => void | - | Fired before moving forward | | onTryMovePrevPage | (prevPage: number) => void | - | Fired before moving back | | onClickCenter | MouseEventHandler<HTMLButtonElement> | - | Callback when center area is clicked | | className | Partial<Record<string, string>> | - | Custom class names for styling | | text | { expansion?, fullScreen?, move?, normal?, thumbnails? } | - | Custom text for UI buttons |

Controlled mode

By default the viewer owns currentPage and isExpansion, and reports changes through onChangeCurrentPage / onChangeExpansion.

Pass currentPage or isExpansion to take that state over. The viewer then renders whatever you give it and never writes the value itself — the callbacks become requests you are free to ignore. This is what lets you drive the viewer from a table of contents, keep it in sync with the URL, or refuse a move.

const [currentPage, setCurrentPage] = useState(0);

<ComicViewer
  currentPage={currentPage}
  pages={pages}
  onTryMoveNextPage={(nextPage) => {
    // Runs before the move. Good place to prefetch or to gate a chapter.
  }}
  onChangeCurrentPage={setCurrentPage}
/>;

Each prop is independent: controlling currentPage leaves isExpansion uncontrolled, and the other way around.

Rendering your own pages

An entry of pages may be a function receiving the class name the viewer would have applied to its own <img>. Use it to bring your own image element, for lazy loading or a custom placeholder.

const pages: PageRenderer[] = urls.map(
  (url) =>
    ({ className }) =>
      <img src={url} alt="" className={className} loading="lazy" />,
);

The function is called during render, so it may not use hooks.

Keyboard Shortcuts

| Key | Action | | ----------- | ------------------------------------- | | Arrow Left | Next page (RTL) / Previous page (LTR) | | Arrow Right | Previous page (RTL) / Next page (LTR) | | Escape | Exit fullscreen |

Touch Gestures

| Gesture | Action | | ----------- | -------------------- | | Swipe left | Navigate pages | | Swipe right | Navigate pages | | Single tap | Toggle UI visibility | | Double tap | Toggle zoom (2x) |

Browser Support

Full Screen API is not supported on iOS. The fullscreen button will not be displayed on unsupported browsers.

License

MIT