@outbook/webcomponents-player-artwork

This package provides a web component for displaying player artwork. It supports responsive images via srcset, multiple sources for <picture> elements, and a customizable fallback icon when no image is provided.

Installation

npm install @outbook/webcomponents-player-artwork

Usage

As a Lit Element (using wrapper function)

The PlayerArtwork wrapper function simplifies usage within Lit templates.

import { html } from 'lit';
import { PlayerArtwork } from '@outbook/webcomponents-player-artwork';
import { music_note } from '@outbook/icons';

function render() {
  return html`
    ${PlayerArtwork({
      src1x: 'path/to/image.jpg',
      src2x: 'path/to/[email protected]',
      icon: music_note
    })}
  `;
}

Direct HTML Usage (using component tag)

You can use the custom element directly in your HTML. Note that complex properties like icon must be set via JavaScript, while sources can be passed as a JSON string.

import '@outbook/webcomponents-player-artwork';

<!-- Simple usage -->
<outbook-player-artwork
  src1x="path/to/image.jpg"
  src2x="path/to/[email protected]"
></outbook-player-artwork>

<!-- With sources for <picture> element -->
<outbook-player-artwork
  sources='[{"media": "(min-width: 600px)", "src1x": "large.jpg"}]'
></outbook-player-artwork>

<!-- With fallback icon (default is music_note) -->
<outbook-player-artwork></outbook-player-artwork>

Component Usage

The component is best used via its wrapper function PlayerArtwork.

Properties

The properties listed below are used by the PlayerArtwork wrapper function.

| Attribute | Property | Type | Default | Description | |-----------------|----------------|-----------|--------------|--------------------------------------------------------------------------------------------------------------------| | class | extraClasses | String | undefined | CSS classes to apply to the host element. | | natural-ratio | naturalRatio | Boolean | false | Natural ratio preseves original image ratio. | | src1x | src1x | String | undefined | The source URL for the 1x resolution image. | | src2x | src2x | String | undefined | The source URL for the 2x resolution image. | | sources | sources | Array | [] | An array of source objects for <picture> usage. Each object should have media, src1x, and optionally src2x. | | - | icon | Object | music_note | The SVG icon object to display as a fallback. Must be passed as a property. |

Sources Object Structure

The sources array expects objects with the following structure:

{
  media: '(min-width: 600px)',
  src1x: 'path/to/large-image.jpg',
  src2x: 'path/to/[email protected]'
}

Styling

This component uses Shadow DOM, and its styles are self-contained. The component's styles are automatically applied and encapsulated.

Custom Properties

You can customize the appearance using the following CSS custom properties:

| Custom Property | Description | |---|---| | --outbook-player-artwork--background-color | Background color of the artwork container. | | --outbook-player-artwork--text-color | Color of the fallback icon. | | --outbook-player-artwork--crystal-background | Background styling for the crystal effect (fallback mode). | | --outbook-player-artwork--crystal-border | Border styling for the crystal effect (fallback mode). |

License

This component is licensed under the Apache-2.0 License.