ptcs-image¶
Overview¶
A ptcs-image displays an image file. It supports the image file formats that the browser supports
The widget is read-only, not responding to user interaction.
The dimensions of the image is either: - relative to the intrinsic dimension of the image, or - expands to the dimensions of the image container, or - specified in CSS units that are independent of the image and its container
If the image size is relative to its container the image is either stretched or contracted to match the container dimension (ignoring the aspect ratio) or cropped or only partially fills the container.
Usage Examples¶
Image with intrinsic width and height¶
<ptcs-image src="image.png"></ptcs-image>
Image with 'small' predefined dimensions¶
<ptcs-image size="small" src="image.jpg"></ptcs-image>
Image with half the intrinsic dimensions¶
<ptcs-image size="50%" src="image.png"></ptcs-image>
Image resized to fill its container¶
<ptcs-image size="fit" src="image.png"></ptcs-image>
Component API¶
Properties¶
| Property | Type | Description |
|---|---|---|
| alt | String | A descriptive text of the image, mainly intended for screen readers. This text is also displayed if the image cannot be loaded |
| labelVariant | String | ptcs-label variant for the label text (default: label) |
| position | String | Specifies the position of the image when size is either contain, cover, fit-x or fit-y. See below for details. |
| size | String | Specifies the size of the image. See below for details. |
| src | String | The source / url of the image |
| preventCaching | Boolean | Prevents the image source from being cached so that the most recent version is shown when reloaded |
| noPlaceholder | Boolean | Don't show placeholder image if the src property is not populated |
The size property¶
The size property specifies the dimension of the displayed image.
size = auto | cover | contain | fit | fit-x | fit-y | small | medium | large | xlarge | length | length auto | auto length | length length
| Value | Description |
|---|---|
auto |
The image is displayed with its original dimensions. This is the default value. |
cover |
The image is resized, retaining the aspect ratio, to cover the area of the container element. If the container has a different aspect ratio a part of the image will be truncated. This can be controlled with the position property. (See below) |
contain |
The image is resized, retaining the aspect ratio, to fit inside the container element. If the container has a different aspect ratio a part of the container background will be visible. This can be controlled with the position property. (See below) |
fit |
The image is resized to completly fill the container element. The aspect ratio is not retained. |
fit-x |
The image is resized to completly fill the container element horizontally, retaining the aspect ratio. The image may therefore be clipped vertically or part of the container might be visible above and / or below the image. This can be controlled with the position property. (See below) |
fit-y |
The image is resized to completly fill the container element vertically, retaining the aspect ratio. The image may therefore be clipped horizontally or part of the container might be visible to the left and / or to the right of the image. This can be controlled with the position property. (See below) |
medium |
Sets width and height to 40px |
large |
Sets width and height to 80px |
xlarge |
Sets width and height to 140px |
| length | Same as length auto (See below) |
length auto |
length specifies the width of the image. The aspect ratio is retained. |
auto length |
length specifies the height of the image. The aspect ratio is retained. |
| length length | The first length specifies the width of the image and the second length the height |
Note:
- a length is a number directly followed by a optional unit (no whitespace between)
- if no unit is specified the default is px
- the unit % specifies the length as a percentage
relative to the intrinsic width or height of the image
The position property¶
The position property specifies where the image will be positioned inside its container if either parts of the image is cropped (in cover mode) or if parts of the container is visible (in contain mode).
The value consist of a combiation of keywords:
| Keyword | Description |
|---|---|
center |
center the image horizontally or vertically or in both directions |
bottom |
place the image at the bottom side of the container |
left |
place the image at the left side of the container |
right |
place the image at the right side of the container |
top |
place the image at the top side of the container |
The default value is: left top
Events¶
| Name | Data | Description |
|---|---|---|
| load | ev.detail.naturalWidth, ev.detail.naturalHeight | Generated when the image has been succesfully loaded (intrinsic size details) |
| error | - | Generated if there is an error loading the image |
Methods¶
No methods
Styling¶
Parts¶
| Part | Description |
|---|---|
| alt-label | Label that shows the alt text if the image can't be loaded |
| image | The image container |
State attributes¶
| Attribute | Description | Part |
|---|---|---|
| container-dim | Is the image dimension dependent on the container? | :host |
| error | Was there an error when loading the image? | :host |