Chuci is a standalone multimedia swiper and viewer Web Components library, extracted from Quyuan. It provides a touch-enabled carousel and multimedia viewers (images, panoramas, videos, YouTube, 3D models, Gaussian splats) without any framework dependencies. The project name comes from 楚辞 (Chuci), an ancient Chinese anthology of poems.
Chuci is open-source under the MIT License.
Read this document in Japanese / 日本語で読む
- Framework-agnostic: pure Web Components, works with any framework or vanilla JS
- Touch-enabled carousel built on Swiper.js
- Multiple media types: images, panoramas, videos, YouTube, 3D models, Gaussian splats
- Zero dependencies: all dependencies bundled (no Lit dependency)
- Lightweight with tree-shaking support and full TypeScript definitions
Release-dependent information (ADR-0012). The CDN example below uses
@latest; pin a specific version for production use.
# pnpm (recommended)
pnpm add @c4h/chuci
# npm
npm install @c4h/chuci<cc-swiper>
<cc-swiper-slide
thumbnail-url="thumb1.jpg"
image-url="full1.jpg"
image-type="image"
caption="First image">
</cc-swiper-slide>
<cc-swiper-slide
thumbnail-url="thumb2.jpg"
image-url="full2.jpg"
image-type="image"
caption="Second image">
</cc-swiper-slide>
</cc-swiper>
<script type="module">
import '@c4h/chuci'
</script><script src="https://cdn.jsdelivr.net/npm/@c4h/chuci@latest/dist/chuci.umd.js"></script>
<script>
// Components are available globally as Chuci
// Use custom elements directly in HTML
</script>- API signatures (release-dependent): see
docs/api/
Clone the repository and install dependencies.
git clone https://github.com/code4history/Chuci.git
cd Chuci
pnpm installpnpm run devpnpm run buildpnpm testRuntime requirements (ADR-0012: release-dependent).
- Node.js:
20or higher - pnpm:
9.0.0or higher (recommended) - Browser: any modern browser supporting Web Components
- Chrome / Edge 79+
- Firefox 63+
- Safari 12.1+
Chuci is part of the Maplat ecosystem by Code for History. See the full ecosystem map (8 repositories + product/corporate sites):
📖 Ecosystem Map — (the diagram is currently kept in a private planning repository; the Sister repositories table below is the public substitute)
| Repository | License | npm | Role |
|---|---|---|---|
| Maplat | Apache 2.0 | @maplat/ui |
Main viewer |
| MaplatCore | Apache 2.0 | @maplat/core |
Core library |
| MaplatTin | Apache 2.0 | @maplat/tin |
TIN conversion |
| MaplatTransform | Apache 2.0 | @maplat/transform |
Coordinate transform |
| MaplatEditor | Apache 2.0 | — | Data authoring tool (desktop) |
MaplatEditor is the data authoring tool used to create the maps and POIs that the viewers above render. The Maplat ecosystem is end-to-end: author with MaplatEditor, serve with any of the viewer libraries.
MIT License — see LICENSE.
Copyright (c) 2024-2026 Code for History
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
If you are migrating from the original Quyuan implementation:
- Change imports from
quyuanto@c4h/chuci - Component names remain the same (
cc-swiper,cc-swiper-slide, etc.) - 3D model URLs no longer use pipe-separated format:
<!-- Old --> <cc-swiper-slide image-url="model.obj|model.mtl" ...> <!-- New --> <cc-swiper-slide image-url="model.obj" material-url="model.mtl" ...>
Extracted from Quyuan by Code for History.