Newskit Logo

Image

Overview

Simple component for adding images. The image component provides a <picture> and an <img> element inside it to place the image in the dom.

Props

srcstring
Image file path that is used directly in the 'src' attribute of the internal 'img' element.
altstring
Image description that is used directly in the 'alt' attribute of the internal 'img' element.
loadingAspectRatioMQ<string>
This is a string interpolation of the aspect ratio of the loading container of the image. This is also used to determine the height or width of the image if only one dimension is provided.
placeholderIconboolean = false
Show the placeholder icon whilst the image is loading.
renderOnServerboolean
This prop need to be set to `true` when the Image component is rendered on the server without client-side javascript.
sourcesImageSource[]
This prop utilize underlying Picture element and generates Source elements from the privided array of ImageSource. For detailed inforamtion how it works check out MDN. ImageSource exnteds Image Source element, the only difference is that you can use breakpoint key (xs | sm | md | lg | xl) as media instead of passing media query.
overridesobject
If provided, overrides the respective presets for the component and provided elements.
stylePresetMQ<string>
If provided, this overrides the style preset applied to the image.
widthMQ<string> = 100%
Used in combination with `height` to calculate the aspect ratio for the image. Generally supply the width px value if known, if not supply horizontal aspect ratio. Both width and aspectRatio should be supplied in a consistent manner.
heightMQ<string> = auto
Used in combination with `width` to calculate the aspect ratio for the image. Generally supply the height px value if known, if not supply vertical aspect ratio. Both width and aspectRatio should be supplied in a consistent manner.
maxWidthMQ<string>
This property sets the maximum width of the image. It prevents the used value of the width property from becoming larger than the value specified by maxWidth.
maxHeightMQ<string>
This property sets the maximum height of the image. It prevents the used value of the height property from becoming larger than the value specified for maxHeight.
placeholderIconOverride<NewsKitIcon>
If provided, this overrides the default placeholder icon.
Refer to the defaults below for the object structure:
{
  stylePreset: "imageSharp"
}

Notes

The aspect width/height is only used on loading state.

Newskit v4.0.0 removed the in-built Caption in <Image/> component but you can still use <Caption/> component together with <Image/> component. Please see the example below:

For more information on the overrides of <Caption/> component, please refer to the Caption documentation.

Playground

Example
Placeholder icon
Image Style Preset
import React from 'react';
import { Image } from 'newskit';

export default () => (
  <Image
    src="static/placeholder-3x2.png"
    alt="Example"
    width="300"
    maxWidth="300"
    height="200"
    maxHeight="200"
    loadingAspectRatio="3:2"
    overrides={{ stylePreset: 'imageSharp' }}
  />
);

For more information on overriding component defaults, see the docs here.

Styling

The image component is block level element and it wraps its boundaries around the internal img element and the dimenstions of the image file provided. Change or limit the width of the component by styling the returned wrapper.

Placeholder icon can be overridden in the theme with a different icon if needed.

Accessibility

Provide an alternative text description for the image via its alt prop. This will allow screen readers and other text based browsers to understand the image.

Colour

Text and background colours must have a 3:1 minimum contrast ratio. Hover states should have clear contrast change or should include a non colour designator. Placeholder icon colour is taken from inkNonEssential token Placeholder background colour is taken from skeleton010 token