Skip to content

Commit

Permalink
docs: more updates based on PR feedback.
Browse files Browse the repository at this point in the history
  • Loading branch information
cjpillsbury committed May 11, 2023
1 parent 7be393e commit 3b2552c
Showing 1 changed file with 17 additions and 12 deletions.
29 changes: 17 additions & 12 deletions docs/src/pages/en/styling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@ Media Chrome provides a lot of ways to easily customize the look and feel of you
* Using breakpoints for mobile-first, responsive design
* Using CSS `:part()` for complex component styling

## The Basics

Just to have a baseline, let's start with a simple player UI built with Media Chrome that uses `<media-play-button>`.

<SandpackContainer
Expand All @@ -28,7 +26,7 @@ Just to have a baseline, let's start with a simple player UI built with Media Ch
</media-controller>`}
/>

## Media Chrome + CSS Variables
## Styling with CSS variables

While the component looks pretty good out of the box, maybe you want a slightly different color palette. To help make these styling cases easier, Media Chrome provides a set of well defined [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) (also known as "CSS Variables"). Here's an example where we've changed the default color of the `<media-play-button>`'s icon, background, and hover background.

Expand All @@ -53,7 +51,7 @@ You may have noticed that the names of these variables make no specific mention

Each Media Chrome component has a pretty wide set of useful variables, including the color-related styles you see, font related styles, padding and sizing styles, and several others, which you can find in the reference section of each component's documentation. For example, you can find a full list of `<media-play-button>` CSS Variables [here](./components/media-play-button#css-variables). For a complete list of Media Chrome CSS variables, check out our [styling reference](./reference/styling).

## Media Chrome + Custom Icons
## Using custom icons

Being able to easily customize a variety of CSS properties is great, but that's not where custom styling stops with Media Chrome. For example, for any of our components with icons, you can override the defaults by passing in your version as a child element with the expected [`slot` attribute](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#adding_flexibility_with_slots), which identifies which state the icon is for. Here's an example of adding custom `play` and `pause` SVG icons to our previous example. Notice that these SVGs still inherit our custom icon color.

Expand Down Expand Up @@ -110,14 +108,25 @@ Earlier, I mentioned that you can use whatever you want for your "icons". This i
</media-controller>`}
/>

## Advanced - Recommendations for custom icons

There are a few things that we typically recommend when using custom icon images to make them work as smoothly as possible with Media Chrome.

1. While you can slot anything, we recommend SVGs, since they tend to be an efficient and scalable (hence the name) image format that is also easier to do things like tweak the dimensions of.
2. Avoid hardcoding `height`, `width`, or `fill` color in the SVGs. While not required, this is the best way to ensure that the sizing and coloring styles will be inherited by Media Chrome components and CSS variables.
3. When possible, define the SVG as `viewBox="0 0 24 24"`. You can always use CSS to tweak these details, but this will help ensure that you won't have things like unintended whitespace or have to muck around with the padding of things like your button components.

## Styling Multiple Components

In the previous example, I ended up using different CSS variables for my font-based icons vs. the SVG-based ones. This also applies for other color styles used in Media Chrome components. Since folks will typically want a consistent palette for their media player, Media Chrome has a couple of "color palette" CSS variables that work as defaults for some of the CSS variables used above: `--media-primary-color`, which you can think of as a "foreground" color, and `--media-secondary-color`, which you can think of as a "background" color. This makes styling multiple Media Chrome components easier with just a few CSS variables.

To demonstrate this, here's an example with several more components, including a range component (`<media-time-range>`), a text-based button component (`<media-playback-rate-button>`), and a text-based display component (`<media-time-display>`). All of these are styled using just 3 CSS variables. If you look at the `custom-styles.css`, you'll also see some of the related CSS variables commented out so you can experiment with their relationships.

<SandpackContainer
stacked
active="css"
height={900}
editorHeight={450}
css={`media-controller {
--media-primary-color: mistyrose;
--media-secondary-color: rgb(27 54 93 / 0.85);
Expand Down Expand Up @@ -216,6 +225,10 @@ media-captions-button:not([mediasubtitleslist]) {
We've already seen a number of ways to customize the look and feel of things in Media Chrome. But one easy way to get a lot of reasonable styles "out of the box" is by using Media Chrome's container components. This next example uses `<media-control-bar>` with `<media-controller>` to show some of these super powers.

<SandpackContainer
stacked
active="css"
height={900}
editorHeight={450}
css={`media-controller {
--media-primary-color: mistyrose;
--media-secondary-color: rgb(27 54 93 / 0.85);
Expand Down Expand Up @@ -472,13 +485,5 @@ media-controller:not([mediapaused])[userinactive]::part(centered-layer) {
</media-controller>`}
/>

## Advanced - Recommendations for custom icons

There are a few things that we typically recommend when using custom icon images to make them work as smoothly as possible with Media Chrome.

1. While you can slot anything, we recommend SVGs, since they tend to be an efficient and scalable (hence the name) image format that is also easier to do things like tweak the dimensions of.
2. Avoid hardcoding `height`, `width`, or `fill` color in the SVGs. While not required, this is the best way to ensure that the sizing and coloring styles will be inherited by Media Chrome components and CSS variables.
3. When possible, define the SVG as `viewBox="0 0 24 24"`. You can always use CSS to tweak these details, but this will help ensure that you won't have things like unintended whitespace or have to muck around with the padding of things like your button components.

{/* Add a second advanced section about WCAG / A11Y + Styling. */}

0 comments on commit 3b2552c

Please sign in to comment.