<gcp-img>
The Custom Element <gcp-img>
element wraps an image from Google Cloud Storage into the document.
This web component follows the open-wc recommendation.
Demo Page
Table of Contents
- Concept
- Philosophy
- Installation
- Usage
- Attribute Summary
- Recommended Options
- How to Contribute
Concept
Google offers an API for serving images uploaded to Google Cloud Storage through a high-performance, dynamic image-serving infrastructure.
The system provides users with a way to perform many operations on images on-the-fly – making it extremely well-suited for developers to implement assets sized, cropped, formatted, etc. in the right direction for the user – with no added work.
For example, the image-serving infrastructure can reformat (JPG, PNG, WEBP), resize or crop, and transform the image in several ways on-the-fly.
This Web Component provides a web developer-friendly way to take advantage of those characteristics.
Philosophy
Out of the box, this web component aims to provide the best performant and accessible experience for web images.
Some of the defaults to accomplish this are:
- Serve images with an effective cache policy of 365 days
- Serve images in WebP format in browsers where it is supported
- Properly size images
- Efficiently encode images
- Native Lazy-loading
Installation
npm i gcp-img
Usage
The above example shows usage of the <gcp-img>
element:
- The
src
attribute is required and contains the path to the image you want to embed from Google Cloud Services. - The
alt
attribute holds a text description of the image, which isn't mandatory but is incredibly useful for accessibility — screen readers read this description out to their users, so they know what the image means. Alt-text is also displayed on the page if the image can't be loaded for some reason: for example, network errors, content blocking, or linkrot.
Setting Dimensions
The above example shows usage of the size
attribute:
- The
size
attribute holds the numeric value of the image dimensions to be displayed. It works as an Aspect Ratio to prevent layout shifting. It is recommended to include it.
A fixed width
The above example shows usage of the fixed
attribute:
- The
fixed
attribute makes the image with the specifyied width on thesize
attribute.
Setting a Dark mode image alternative
The above example shows usage of the darksrc
attribute:
- The
darksrc
attribute contains the path to an alternate dark version of the image you want to embed from Google Cloud Services. - It will be displayed if
prefers-color-scheme: dark
is supported and activated.
Setting Responsive Dimensions
The above example shows usage of the read-only config
attribute:
- The
config
attribute holds a JS object converted to text with the configuration of the image to be displayed.
"screen": 320 "size": 320 "screen": 600 "size": 640 "screen": 1024 "size": 960
The above configuration will request:
- A
320px
width image on a viewport with the size of 320 - A
640px
width image on a viewport with the size of 600 - A
960px
width image on a viewport with the size of 1024
You can specify as many configuration values as you need.
Art Directed Image
In case you need to show a different image in certain viewport, you can specify the source in the configuration:
"screen": 320 "size": 320 "screen": 600 "size": 640 "source": "https://lh3.googleusercontent.com/…" "screen": 1024 "size": 960
The above configuration will render a different image between the viewports with dimensions of 320, 640 and 1024.
Configuration Options
Attribute | Required | Type | Description |
---|---|---|---|
screen |
Yes | number |
The screen size where the configuration values are intended. |
size |
Yes | number |
The width of the image for the companion screen size. |
source |
No | URL | The path to the image you want to embed from Google Cloud Services. |
dark |
No | URL | The path to the dark mode version image you want to embed from Google Cloud Services. |
Change the Cache TTL (Time to live)
By default the images will be requested with a cache for one year (365 Days).
To change the number of days you can specify the new number of days in the read-only ttl
attribute.
Applying Transformations
Rotation
The above example shows usage of the rotate
attribute:
- You can rotate images only with
90
,180
, or270
value for the degrees clockwise.
Flip
The above example shows usage of the flip
attribute:
- You can flip images vertically with
v
or horizontally withh
.
Applying Filters
Blur
The above example shows usage of the blur
on the filter
attribute:
- You can blur images by specifying a
radius
value between0
and100
.
Vignette
The above example shows usage of the vignette
on the filter
attribute:
- You can vignette images by specifying a
radius
value between0
and100
.
Invert
The above example shows usage of the invert
on the filter
attribute:
- You can make images invert by specifying a value of
invert
.
Black and White
The above example shows usage of the bw
on the filter
attribute:
- You can make images black and white by specifying a value of
bw
.
Applying Crop
Smart Crop
The above example shows usage of the smart
the crop
attribute:
- You can make images square crop by specifying a value of
smart
.
Circular Crop
The above example shows usage of the circular
the crop
attribute:
- You can make images circular crop by specifying a value of
circular
.
Animated Images
The above example shows usage of the play
attribute:
- You can start the animation of GIF or WEBP images by specifying an attribute of
play
.
Attribute Summary
Attribute | Required | Read-only | Type | Default | Description |
---|---|---|---|---|---|
src |
Yes | No | URL | null |
The path to the image you want to embed from Google Cloud Services. |
darksrc |
No | No | URL | null |
The path to the image you want to show if prefers-color-scheme: dark is supported. |
alt |
No | No | String | empty | A text description of the image. |
fixed |
No | No | Boolean | false |
When specifying a single source will fix the dimensions to the values on size attribute. |
size |
No | No | Number | null |
The numeric value of the image width to be displayed. |
config |
No | Yes | String | null |
A JS object converted to text with the configuration of the image to be displayed. |
ttl |
No | Yes | Number | 365 |
The number of days to cache the image. Default value is recommended. |
rotate |
No | No | Number | null |
The value for the degrees clockwise to rotate the image. Only accepts 90 , 180 , or 270 . |
flip |
No | No | String | null |
Flip images vertically with v or horizontally with h . |
filter |
No | No | String | null |
Apply a filter to the image by specifying blur , vignette , invert or bw . |
radius |
No | No | Number | 0 |
Radius value between 0 and 100 . For blur and vignette filters. |
color |
No | No | String | 000000 |
A Hexadecimal color number value to apply into the vignette filter. |
crop |
No | No | String | null |
Turn the image into a square or circle by specifying smart or circular . |
play |
No | No | Boolean | false |
If the image source is an animated GIF/WEBP it will play it with autoloop. |
Read-only properties mean if the attribute change on-the-fly, the image does not get updated to reflect the new value.
Recommended Options
To provide a better user experience is recommended to provide a fallback image for No-JS scenarios and a placeholder image for slow networks.
Fallback Image
The above example adds a <noscript>
tag with a regular <img>
tag, to show image when JS is desactivated.
It is recommend to add =v3-e365
parameters at the end of the Google Cloud Image URL, to serve a smaller image.
Placeholder Image
The above example adds an image with the attribute slot
with the value placeholder
to be used as a placeholder while the image is lazy loaded.
It is recommended to provide a very small image, for this reason the example adds the paramaters =w100-v3-e365-fSoften=1,100,0
at the end of the Google Cloud Image URL, to serve a 100px wide, blurry, compressed image.
It is also possible to provide a Base64 Encoded Image as a placeholder.
Or a different element, like a SVG.
Animate Image loading
By including the fade
attribute, the image will animate opacity
from 0
to 1
when lazy-loaded, creating a nice effect.
How to Contribute
Please check the Contributor Guide.