SimplePlayer

A simple default video player created from Grizz's portfolio for others to use.

SimplePlayer is a framework-free Web Component. It gives you a clean default video player with custom overlay controls, a scrubber, volume, Picture-in-Picture, fullscreen, and lazy loading.

Installation

npm install @grizzshutsdown/simpleplayer
pnpm add @grizzshutsdown/simpleplayer
yarn add @grizzshutsdown/simpleplayer
bun add @grizzshutsdown/simpleplayer

Usage

import '@grizzshutsdown/simpleplayer';

<simple-player src="/video.mp4"></simple-player>

Add the extra control tray when you want volume, Picture-in-Picture, and fullscreen:

<simple-player src="/video.mp4" controls></simple-player>

Frameworks

React:

import '@grizzshutsdown/simpleplayer';

export function App() {
  return <simple-player src="/video.mp4" aspect-ratio="16 / 9" />;
}

Vue:

<script setup>
import '@grizzshutsdown/simpleplayer';
</script>

<template>
  <simple-player src="/video.mp4" aspect-ratio="16 / 9" />
</template>

Svelte:

<script>
  import '@grizzshutsdown/simpleplayer';
</script>

<simple-player src="/video.mp4" aspect-ratio="16 / 9" />

TypeScript with React:

import type { DetailedHTMLProps, HTMLAttributes } from 'react';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'simple-player': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
        src?: string;
        'aspect-ratio'?: string;
        'preload-margin'?: string;
        controls?: boolean;
        'disable-autoplay'?: boolean;
      };
    }
  }
}

Options

<simple-player
  src="/video.mp4"
  aspect-ratio="16 / 9"
  preload-margin="360px 0px">
</simple-player>

• src: video URL.
• aspect-ratio: player aspect ratio. Default: 16 / 9.
• preload-margin: lazy-load margin before the video enters view. Default: 360px 0px.
• controls: add volume, Picture-in-Picture, and fullscreen controls.
• disable-autoplay: turn off default autoplay. Autoplay starts muted so browsers allow it.

The default player matches the simple preview: play/pause, scrubber, muted autoplay, and no extra side controls.

Keep the HTML clean and manage controls with JavaScript:

const player = document.querySelector('simple-player');

player.src = '/next-video.mp4';
player.aspectRatio = '1 / 1';
player.preloadMargin = '240px 0px';
player.autoplayEnabled = false;
player.controlsEnabled = true;
player.volumeEnabled = true;
player.volumeSliderEnabled = false;
player.pictureInPictureEnabled = true;
player.fullscreenEnabled = true;

Contributing

npm install
npm run dev

The dev playground lives in dev/ and imports src/simple-player.ts directly. Use it when changing the player itself.

The hosted demo is separate from the package source. It has its own consumer install in site/, then imports the published package the same way a user would:

npm install --prefix site
npm run demo

Cloudflare Pages uses:

npm run build

with site-dist as the output directory.

Before opening a pull request, run:

npm run build
npm pack --dry-run

Styling

simple-player {
  --overlay-soft: rgb(0 0 0 / 0.42);
  --overlay-blur: 0px;

  --sp-glass-surface: rgb(255 255 255 / 0.04);
  --sp-glass-opacity: 0.28;

  --sp-control-glass-surface: rgb(255 255 255 / 0.12);
  --sp-control-glass-opacity: 0.62;
  --sp-control-hover-surface: rgb(255 255 255 / 0.14);
  --sp-control-tray-padding: 2px;
  --sp-control-slot-size: 24px;
  --sp-control-icon-render-size: 20px;
  --sp-control-icon-stroke-width: 1.6;
}

AI Skill

The package includes a plain Markdown skill that any AI tool can read.

npx @grizzshutsdown/simpleplayer

Found this useful?

Follow Grizz.

License

MIT