@gfazioli/mantine-video

中文文档
1.2.10发布于 2026/11/09MITTypeScriptESM + CJS零依赖近 30 天下载 5.3万

A customizable video player component for React built with Mantine. Compound API in Mantine ecosystem style, headless useVideo hook, theme-aware styling, accessibility, and full Styles API.

原始使用文档
文档目录9 节
  1. Overview
  2. Features
  3. Installation
  4. Usage
  5. Custom controls
  6. Headless with useVideo
  7. Picture-in-Picture lifecycle
  8. Variants
  9. Sponsor

Mantine Video Component

Mantine Video

mantine-video at a glance, refreshed daily: commits, releases, stars, issues and pull requests, a year of commit activity, the weekly rhythm, languages, latest commits and releases, contributors
Made with glancecard · refreshed daily

Overview

This component is created on top of the Mantine library. It requires Mantine 9.x and React 19.

Mantine Video is a Mantine‑native video player built on top of the standard HTML <video> element. It pairs a polymorphic root component with a complete compound API (Video.Controls, Video.PlayButton, Video.Timeline, Video.MuteButton, Video.CaptionsButton, Video.PiPButton, Video.FullscreenButton, Video.SkipButton, Video.TimeDisplay) and a fully headless useVideo hook so you can either use the batteries‑included control bar, compose your own with Mantine sub‑components, or build a 100% custom UI on top of the underlying state. Every part is theme‑aware (color scheme, theme colors, radii, sizes), accessible (ARIA labels, keyboard shortcuts, focus management), and customizable through the full Mantine Styles API (classNames, styles, vars, unstyled). Four built‑in variants — overlay, minimal, floating, bordered — cover the most common layouts out of the box. Fullscreen and Picture‑in‑Picture are wired in for browsers that support the standard APIs, with capability‑aware sub‑components that self‑hide when not supported (so you never see a broken button on Firefox).

Features

  • 🎬 Compound API — Video.Controls, Video.PlayButton, Video.SkipButton, Video.Timeline, Video.TimeDisplay, Video.MuteButton, Video.CaptionsButton, Video.PiPButton, Video.FullscreenButton
  • 🪝 Headless useVideo hook — full state (playing, currentTime, duration, buffered, volume, muted, playbackRate, fullscreen, pip, canPlay, canFullscreen, canPiP, isLoading, error) and actions (play, pause, toggle, seek, seekBy, setVolume, toggleMute, setPlaybackRate, toggleFullscreen, togglePiP)
  • 🎭 Four variants — overlay (default, YouTube‑style), minimal, floating, bordered
  • 🎨 Mantine theme integration — color, radius, size props plus full color‑scheme awareness
  • 🎨 Styles API — classNames, styles, vars, unstyled on every part
  • ⌨️ Keyboard shortcuts — Space / K (play/pause), J / L (±10s), ←/→ (±5s), ↑/↓ (volume), M (mute), F (fullscreen), P (PiP)
  • 🖥️ Fullscreen + Picture‑in‑Picture out of the box, capability‑aware
  • 🗣️ Captions / subtitles via native <track> — toggle button auto‑hides when no tracks present
  • 🔀 Multiple sources — pass a sources array to ship several formats/codecs and let the browser pick the first it can play (each entry supports type and media), with fallbackSrc loaded if every source fails at runtime
  • 🎛️ Controlled + uncontrolled for playing, currentTime, volume, playbackRate
  • ♿ Accessibility — ARIA labels, aria-pressed toggles, focus‑visible outlines
  • 📦 TypeScript — full type safety, every prop documented

[!note]

→ Demo and Documentation → Youtube Video → More Mantine Components

Installation

npm install @gfazioli/mantine-video

or

yarn add @gfazioli/mantine-video

After installation import package styles at the root of your application:

import '@gfazioli/mantine-video/styles.css';

Or use the layered version inside @layer mantine-video:

import '@gfazioli/mantine-video/styles.layer.css';

Usage

The simplest usage — pass src, optionally poster and aspectRatio, and you get a fully themed player with play / pause, seekable timeline, time display, volume, captions, picture‑in‑picture and fullscreen out of the box:

import { Video } from '@gfazioli/mantine-video';

function Demo() {
  return (
    <Video
      src="https://example.com/video.mp4"
      poster="https://example.com/poster.jpg"
      aspectRatio={16 / 9}
    />
  );
}

Custom controls

The default control bar is just a sensible composition of compound sub‑components. Pass controls={false} and provide your own <Video.Controls> children to fully customize the layout — reorder, drop, add or theme any part:

import { Video } from '@gfazioli/mantine-video';

function Demo() {
  return (
    <Video src="https://example.com/video.mp4" aspectRatio={16 / 9} controls={false}>
      <Video.Controls>
        <Video.PlayButton />
        <Video.SkipButton seconds={-10} />
        <Video.SkipButton seconds={10} />
        <Video.Timeline />
        <Video.TimeDisplay format="current/-remaining" />
        <Video.MuteButton />
        <Video.CaptionsButton />
        <Video.PiPButton />
        <Video.FullscreenButton />
      </Video.Controls>
    </Video>
  );
}

Headless with useVideo

If you need a completely custom UI, skip <Video> and use the useVideo hook directly. It returns the video state and a full set of actions; just bind the videoRef to a native <video> element:

import { ActionIcon, Slider } from '@mantine/core';
import { IconPlayerPauseFilled, IconPlayerPlayFilled } from '@tabler/icons-react';
import { useVideo } from '@gfazioli/mantine-video';

function Demo() {
  const video = useVideo();

  return (
    <div>
      <video ref={video.videoRef} src="https://example.com/video.mp4" />
      <ActionIcon onClick={video.toggle}>
        {video.playing ? <IconPlayerPauseFilled /> : <IconPlayerPlayFilled />}
      </ActionIcon>
      <Slider value={video.currentTime} max={video.duration} onChange={video.seek} />
    </div>
  );
}

Picture-in-Picture lifecycle

Hook into the user popping the video in and out — for example to dim a sidebar or show a "playing in PiP" indicator elsewhere on the page:

<Video
  src="..."
  onEnterPictureInPicture={() => console.log('entered PiP')}
  onLeavePictureInPicture={() => console.log('left PiP')}
/>

Variants

VariantDescription
overlay (default)Controls float over the bottom of the video with a gradient backdrop, fade in on hover, auto‑hide while playing
minimalControls placed below the video in the page flow, no overlay
floatingLike overlay but the bar is a rounded floating card with a blurred backdrop
borderedBordered container wraps both video and controls below, ideal for cards / lists

Sponsor

Your support helps me:

  • Keep the project actively maintained with timely bug fixes and security updates
  • Add new features, improve performance, and refine the developer experience
  • Expand test coverage and documentation for smoother adoption
  • Ensure long‑term sustainability without relying on ad hoc free time
  • Prioritize community requests and roadmap items that matter most

Open source thrives when those who benefit can give back—even a small monthly contribution makes a real difference. Sponsorships help cover maintenance time, infrastructure, and the countless invisible tasks that keep a project healthy.

Your help truly matters.

💚 Become a sponsor today and help me keep this project reliable, up‑to‑date, and growing for everyone.

版本与发布记录

@gfazioli/mantine-video 共发布 19 个版本,首次发布于 2026/05/18;过去 12 个月发布了 19 个版本。

版本发布日期距今
1.2.10latest2026/11/096 天前
1.2.92026/11/069 天前
1.2.82026/10/2621 天前
1.2.72026/10/2224 天前
1.2.62026/10/131 个月前
1.2.52026/10/101 个月前

关于 @gfazioli/mantine-video 的常见问题

@gfazioli/mantine-video 是什么?

A customizable video player component for React built with Mantine. Compound API in Mantine ecosystem style, headless useVideo hook, theme-aware styling, accessibility, and full Styles API.

如何安装 @gfazioli/mantine-video?

在项目目录运行 npm install @gfazioli/mantine-video,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18.x || ^19.x)、react-dom(^18.x || ^19.x)、@mantine/core(>=9.0.0)、@mantine/hooks(>=9.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gfazioli/mantine-video 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gfazioli/mantine-video 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gfazioli/mantine-video 可以商用吗?

@gfazioli/mantine-video 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gfazioli/mantine-video 的下载量有多少?

根据 npm 官方下载统计,@gfazioli/mantine-video 在 2026/10/17 – 2026/11/15 这 30 天内被下载 53,275 次,日均约 1,776 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gfazioli/mantine-video 还在维护吗?

最新版本 1.2.10 发布于 2026/11/09(6 天前);至今共发布 19 个版本,其中过去 12 个月发布了 19 个;首次发布于 2026/05/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。