[Docs] Where to set poster? (Poster vs Video vs video)

[pietrop]

Poster in docs

The <Poster> component loads and displays the current media poster image. When this component is present, the poster attribute will not be applied to the media provider to prevent double loading. Furthermore, this element will respect the loading strategy defined on the media provider; therefore, the poster won't load until the media can (lazy).

We recommend using <Poster> over the HTML5 poster attribute because the behavior will be more consistent browser-to-browser. The native poster will sometimes load and disappear as soon as the first media frame is ready depending on your preload setting. Secondly, you can place this poster over the media and controls while loading to improve the overall design; you can't do this if using the native poster attribute because it lives inside the browser's media element.

I think it's great that there's this optimization and this explanation but I find it slightly confusing. In terms of what to do, and where to set the poster in practice. And perhaps the code example could be used to clarify this a bit more?

Does the above, means this (setting poster on Video):

<Video loading="visible" poster={poster}>
  <video src={src} preload="none" data-video="0" >
    <track kind="captions" />
  </video>
</Video>
<Poster alt="Agent 327 blowing flames with a hair dryer." />

Or does it means this (setting poster on Poster):

- <Video loading="visible" poster={poster}>
+  <Video loading="visible" >
            <video src={src} preload="none" data-video="0" >
              <track kind="captions" />
            </video>
          </Video>
-  <Poster alt="Agent 327 blowing flames with a hair dryer." />
+  <Poster alt="Agent 327 blowing flames with a hair dryer." poster={poster}/>

I tried this last one,poster on Poster and it didn't work, but I still wanted to double check what were the intentions.

Happy to do a PR to clarify the docs

[pietrop]

I also wonder if some of the info for the HTML (web components) version is also applicable for React?

HTML - Media Poster

You can declare a second poster in your markup like so:

<vds-video poster="https://media-files.vidstack.io/poster.png">
  <!-- Poster is shown while loading or if JS disabled. -->
  <video poster="https://media-files.vidstack.io/poster-seo.png"></video>
</vds-video>

The one on the Vidstack provider element is the poster that you expect your users to load and see. The other on the <video> element is shown temporarily as the primary poster loads, or if JavaScript is disabled by a client or crawler (i.e., search engine).

You can choose to load a low-res image that the user will see while the main poster is loading or a 124x70 (or greater) sized image explicitly designed to show in search results.

[mihar-22]

And perhaps the code example could be used to clarify this a bit more?

Ah I see that this can be confusing. There is a poster usage example code snippet that shows it's set on <Video>. Was this not loading/visible or not helpful? I see that the styling example is missing it, maybe we should add it there too incase the usage one is missed.

I also wonder if some of the info for the HTML (web components) version is also applicable for React?

Yep it can be applied to React as well, in terms of setting the poster element on both the React <Video> component and native <video> element.

[mihar-22]

We could add a src property to <Poster> to allow setting it there too, but then you could set it in two places which could lead to additional confusion.

[pietrop]

I see that the styling example is missing it, maybe we should add it there too incase the usage one is missed.

Yes, think so

We could add a src property to to allow setting it there too, but then you could set it in two places which could lead to additional confusion.

Yeah, probably best to keep it into one place.

So the idea is that poster is set on Video because if you don't have Poster component, then it just puts it on video element?

[mihar-22]

So the idea is that poster is set on Video because if you don't have Poster component, then it just puts it on video element?

Yep, a form of progressive enhancement I guess. It also enables us to control when the poster is loaded.

[pietrop]

ok, cool, I think we could make it more explicit in the docs, so that the guiding principle is clear.