Migration Guide: `0.6.x` to `1.0@next` #949

mihar-22 · 2023-10-10T10:50:43Z

mihar-22
Oct 10, 2023
Maintainer

👋

I apologize for not having this earlier. I made some assumptions that the migration path is simple but it was brought to my attention that it would be helpful to outline how to upgrade. I've noted the main things below, if something is missing please let me know in the comments below.

The following categories are listed below:

General
React
CDN
Web Components

General

Global Types

Global types are no longer required and can be removed from tsconfig.json:

- "types": ["vidstack/globals"]

User/Controls

The player.user object is now player.controls.
The data attribute on the player element changed from data-user-idle to data-controls.
The userIdle media state is now controlsVisible.
The player.user.pauseIdleTracking(true) method is now player.controls.pause() and player.controls.resume().

React

Dependencies

You can remove the vidstack dependency as it's no longer required:

npm uninstall vidstack

Update to pre-release:

npm install @vidstack/react@next

MediaOutlet

Change the MediaOutlet component to MediaProvider:

- import { MediaOutlet } from '@vidstack/react';
- <MediaOutlet />

+ - import { MediaProvider } from '@vidstack/react';
+ <MediaProvider />

Styles

- import 'vidstack/styles/base.css';
+ import '@vidstack/react/player/styles/base.css';

- import 'vidstack/styles/defaults.css';
+ import '@vidstack/react/player/styles/default/theme.css';

- import 'vidstack/styles/community-skin/audio.css';
- import 'vidstack/styles/community-skin/video.css';

+ import '@vidstack/react/player/styles/default/layouts/audio.css';
+ import '@vidstack/react/player/styles/default/layouts/video.css';

Community Skin

The MediaCommunitySkin is now the DefaultAudioLayout and DefaultVideoLayout:

- import { MediaCommunitySkin } from '@vidstack/react';
- <MediaCommuitySkin />

+ import { defaultLayoutIcons, DefaultAudioLayout, DefaultVideoLayout } from '@vidstack/react/player/layouts/default';
+ <DefaultAudioLayout icons={defaultLayoutIcons} />
+ <DefaultVideoLayout icons={defaultLayoutIcons} />

Remember to update the styles too (see above).

Thumbnails

The thumbnails property has been removed from player component and moved to the new layouts:

- <MediaPlayer thumbnails="...">

+ <DefaultVideoLayout thumbnails="..." />

Components

Components are no longer prefixed with Media except MediaPlayer and MediaProvider.
Most components still return a DOM element ref. A few like the player return a component instance which you can call methods on.
Some components have been made part of other root components using the builder API. For example, <SliderValue> is now available as Slider.Value, VolumeSlider.Value, and TimeSlider.Value. See the Component API references for more examples.

Default UI

Everything is headless by default now meaning no UI is displayed out of the box. The new examples repo can guide you on how to style your custom player UI.
You can remove the defaultAppearance property.

LiveIndicator

The MediaLiveIndicator component is now LiveButton:

- import { MediaLiveIndicator } from "@vidstack/react";
- <MediaLiveIndicator />

+ import { LiveButton } from "@vidstack/react";
+ <LiveButton />

The data-live-edge attribute was changed to data-edge.

Active Buttons

The active state data attribute of the FullscreenButton (prev data-fullscreen), CaptionButton (prev data-pressed), and PIPButton (prev data-pip) is now data-active.

Tooltips

OLD

import { MediaPlayButton, MediaTooltip } from '@vidstack/react';

<MediaPlayButton defaultAppearance>
  <MediaTooltip position="top start">
    ... 
  </MediaTooltip>
</MediaPlayButton>;

NEW

The new examples repo can guide you on how to properly setup tooltips.

import { PlayButton, Tooltip } from '@vidstack/react';

<Tooltip.Root>
  <Tooltip.Trigger asChild>
    <PlayButton>...</PlayButton>
  </Tooltip.Trigger>
  <Tooltip.Content placement="top start">
    ...
  </Tooltip.Content>
</Tooltip.Root>

Sliders

Slider components now use the builder API. See TimeSlider API reference as an example.
<SliderValue> is now <Slider.Value>, <VolumeSlider.Value>, and <TimeSlider.Value>.
<SliderThumbnail> is now <TimeSlider.Thumbnail>.
<SliderVideo> is now <TimeSlider.Video>.
The data-interactive attribute was changed to data-active.
The slot="preview" was changed to <Slider.Preview>, <VolumeSlider.Preview>, and <TimeSlider.Preview>.
Slider chapters are now a separate component <TimeSlider.Chapters>.
The part="chapter-title" was changed to data-part="chapter-title".

Menus

Menu components now use the builder API. See Menu API reference as an example.
<MediaMenu position="top center"> is now <Menu.Items placement="top center">.
Portals are now separate via Menu.Portal.
Pre-built menus such as <MediaAudioMenuItems>, <MediaCaptionMenuItems>, <MediaQualityMenuItems>, and <MediaPlaybackRateMenuItems> were all removed in favour of hooks. The new hooks are useAudioOptions, useCaptionOptions, useVideoQualityOptions, and usePlaybackRateOptions. They'll all be documented very soon but you can see the examples repo on how to use caption options. The rest are very similar.

Tailwind

Update plugin in tailwind.config from require('vidstack/tailwind.cjs') to require('@vidstack/react/tailwind.cjs').
Remove "tailwindCSS.experimental.classRegex": ["[cC]lass=['\"](.*)['|\"]"] from your VSCode settings as it's no longer required.
All variants are prefixed with media-* now such as media-paused, media-playing, not-media-paused, not-media-playing, etc. You can configure the plugin and remove it.

CDN

Styles

- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/base.min.css" />
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack@next/player/styles/base.min.css" />

-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/defaults.min.css" />
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack@next/player/styles/default/theme.min.css" />

-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/community-skin/audio.min.css" />
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack@next/player/styles/default/layouts/audio.min.css" />

-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/community-skin/video.min.css" />
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack@next/player/styles/default/layouts/video.min.css" />

Scripts

Without layouts (prev headless option):

- <script type="module" src="https://cdn.jsdelivr.net/npm/vidstack/dist/cdn/prod.js"></script>
+ <script src="https://cdn.jsdelivr.net/npm/vidstack@next/cdn/vidstack.js" type="module"></script>

With layouts (prev Community Skin option):

- <script type="module" src="https://cdn.jsdelivr.net/npm/vidstack/dist/cdn/prod.js"></script>
+ <script src="https://cdn.jsdelivr.net/npm/vidstack@next/cdn/with-layouts/vidstack.js" type="module"></script>

👉 From here continue reading the Web Components section below for additional changes.

Web Components

Dependencies

npm i vidstack@next

Media Outlet

Change the media-outlet component to media-provider:

- <media-outlet>
+ <media-provider>

Styles

- import 'vidstack/styles/base.css';
+ import 'vidstack/player/styles/base.css';

- import 'vidstack/styles/defaults.css';
+ import 'vidstack/player/styles/default/theme.css';

- import 'vidstack/styles/community-skin/audio.css';
- import 'vidstack/styles/community-skin/video.css';

+ import 'vidstack/player/styles/default/layouts/audio.css';
+ import 'vidstack/player/styles/default/layouts/video.css';

Community Skin

The media-community-skin element is split into now media-audio-layout and media-video-layout:

- <media-community-skin>
+ <media-audio-layout>
+ <media-video-layout>

Remember to update the styles too (see above).

Thumbnails

The thumbnails property has been removed from player component and moved to the new layouts:

- <media-player thumbnails="...">

+ <media-video-layout thumbnails="..." />

Default UI

Everything is headless by default now meaning no UI is displayed out of the box. The new examples repo can guide you on how to style your custom player UI.
You can remove the default-appearance attribute.

LiveIndicator

The media-live-indicator component is now media-live-button:

- <media-live-indicator>
+ <media-live-button>

The data-live-edge attribute was changed to data-edge.

Active Buttons

The active state data attribute of the FullscreenButton (prev data-fullscreen), CaptionButton (prev data-pressed), and PIPButton (prev data-pip) is now data-active.

Tooltips

OLD

<media-play-button default-appearance>
  <media-tooltip position="top start">
    ... 
  </media-tooltip>
</media-play-button>

NEW

The new examples repo can guide you on how to properly setup tooltips.

<media-tooltip>
  <media-tooltip-trigger>
    <media-play-button>...</media-play-button>
  </media-tooltip-trigger>
  <media-tooltip-content placement="top start">
    ...
  </media-tooltip-content>
</media-tooltip>

Sliders

The data-interactive attribute was changed to data-active.
The slot="preview" was changed to <media-slider-preview>.
Slider chapters are now a separate component <media-slider-chapters>.
The part="chapter-title" was changed to data-part="chapter-title".

Menus

<media-menu position="top center"> is now <media-menu-items placement="top center">.
Portals are now separate via <media-menu-porta>.
<media-audio-menu-items> is now <media-audio-radio-group> and uses templates.
<media-caption-menu-items> is now media-captions-radio-group and uses templates.
<media-quality-menu-items> is now media-quality-radio-group and uses templates.
<media-playback-rate-menu-items> is now media-speed-radio-group and uses templates.

Tailwind

Remove "tailwindCSS.experimental.classRegex": ["[cC]lass=['\"](.*)['|\"]"] from your VSCode settings as it's no longer required.
All variants are prefixed with media-* now such as media-paused, media-playing, not-media-paused, not-media-playing, etc. You can configure the plugin and remove it.
Set webComponents: true option in the Vidstack Tailwind plugin config to optimize selectors:

require('vidstack/tailwind.cjs')({
  // Change the media variants prefix.
  prefix: 'media',
  // Enables more efficient selectors.
  webComponents: true,
});

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Migration Guide: `0.6.x` to `1.0@next` #949

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Migration Guide: 0.6.x to 1.0@next #949

Uh oh!

Uh oh!

mihar-22 Oct 10, 2023 Maintainer

General

Global Types

User/Controls

React

Dependencies

MediaOutlet

Styles

Community Skin

Thumbnails

Components

Default UI

LiveIndicator

Active Buttons

Tooltips

Sliders

Menus

Tailwind

CDN

Styles

Scripts

Web Components

Dependencies

Media Outlet

Styles

Community Skin

Thumbnails

Default UI

LiveIndicator

Active Buttons

Tooltips

Sliders

Menus

Tailwind

Replies: 0 comments

Migration Guide: `0.6.x` to `1.0@next` #949

mihar-22
Oct 10, 2023
Maintainer