Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshfarrant
joshfarrant committed Jun 27, 2024
1 parent fdd0825 commit e20b2e2
Showing 1 changed file with 67 additions and 69 deletions.
136 changes: 67 additions & 69 deletions apps/docs/content/components/Image/react.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,11 @@ description: Use the image component to display a graphical representation.
---

import ComponentLayout from '../../../src/layouts/component-layout'
import {PropTableValues} from '../../../src/components'
import {ImageBorderRadiusOptions} from '@primer/react-brand'
export default ComponentLayout

import {Label} from '@primer/react'
export default ComponentLayout

```js
import {Image} from '@primer/react-brand'
Expand All @@ -20,7 +21,7 @@ import {Image} from '@primer/react-brand'

### Default

This component uses the `img` element by default.
This component renders an `img` element.

```jsx live
<Image
Expand All @@ -31,36 +32,36 @@ This component uses the `img` element by default.

### Picture

The `as` prop can be used to set the container of the image to use `picture`.
As the `Image` component always renders an `img` element, you can wrap it with a `picture` element.

```jsx live
<Image
as="picture"
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
/>
<picture>
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
/>
</picture>
```

### Picture with sources

The `sources` prop can be used to set the source elements within the `picture` component. This can only be used when `as` is set to `picture`.
Add `source` elements as siblings to the `Image` component inside the `picture` element.

```jsx live
<Image
as="picture"
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
sources={[
{
srcset: 'https://via.placeholder.com/600x400/d3d9df/d3d9df.png',
media: '(min-width: 600px)',
},
{
srcset: 'https://via.placeholder.com/900x600/d3d9df/d3d9df.png',
media: '(min-width: 900px)',
},
]}
/>
<picture>
<source
srcset="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
media="(min-width: 600px)"
/>
<source
srcset="https://via.placeholder.com/900x600/d3d9df/d3d9df.png"
media="(min-width: 900px)"
/>
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
/>
</picture>
```

### Image with source set
Expand All @@ -77,27 +78,43 @@ The `srcSet` prop can be used to set the srcSet of the image. This can only be u

### Aspect ratio

The `aspectRatio` prop can be used to set the aspect ratio of the image. This is useful when the image is not the same aspect ratio as the container.

```jsx live
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
aspectRatio="16:9"
/>
```

### Height

The `height` prop can be used to set the height of the image. This can be used along side the `aspectRatio` prop to create a responsive image the same size as other images.
The CSS `aspect-ratio` property (or `style.aspectRatio`) can be used to set the aspect ratio of the image. Note that either `width` or `height` must be set for this to take effect.

```jsx live
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
height={200}
aspectRatio="16:9"
/>
<Stack direction="horizontal" alignItems="flex-start">
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
height={100}
style={{
aspectRatio: '1/1',
}}
/>
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
height={100}
style={{
aspectRatio: '4/3',
}}
/>
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
height={100}
style={{
aspectRatio: '16/10',
}}
/>
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
height={100}
style={{
aspectRatio: '16/9',
}}
/>
</Stack>
```

### Border radius
Expand Down Expand Up @@ -144,33 +161,14 @@ The `borderRadius` prop can be used to apply rounded corners to images using pre
</Stack>
```

### Width

The `width` prop can be used to set the width of the image. This can be used along side the `aspectRatio` prop to create a responsive image the same size as other images.

```jsx live
<Image
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
alt="placeholder, blank area with an off-white background color"
width={200}
aspectRatio="16:9"
/>
```

## Component props

### Image <Label>Required</Label>

| name | type | default | required | description |
| -------------- | -------------------------------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src` | `string` | | `true` | Specifies the path to the image |
| `alt` | `string` | | `true` | Specifies a text value explaining the nature of the image for users of assistive technology |
| `as` | `img`, `picture` | `img` | `false` | Specification to create a picture component |
| `sources` | `{srcset: string, media: string}[]` | | `false` | When picture is specified in the `as` prop sources allows you to set the source elements. |
| `aspectRatio` | `'1:1'`, `'16:9'`, `'16:10'`, `'4:3'`, `'custom'` | `undefined` | `false` | Sets the image aspect ratio. A custom ratio can be provided in the design tokens. |
| `borderRadius` | <PropTableValues values={[...ImageBorderRadiusOptions]} commaSeparated /> | `undefined` | `false` | Applies a system-level border radius value to the Image. |
| `height` | `number` | | `false` | The height of the image element or its container if it has an aspect ratio |
| `width` | `number` | | `false` | The width of the image element or its container if it has an aspect ratio |
| `loading` | `eager`, `lazy` | `eager` | `false` | The loading attribute specifies whether a browser should load an image immediately or to defer loading of off-screen images until for example the user scrolls near them. |
| `decoding` | `sync`, `async`, `auto` | `sync` | `false` | Sets the image decoding strategy. Representing a hint given to the browser on how it should decode the image. |
| `className` | `string` | | `false` | Sets a custom CSS class |
All standard `img` attributes are supported as defined by `React.ImgHTMLAttributes<HTMLImageElement>` with the following additions.

| name | type | default | required | description |
| -------------- | -------------------------------------------------------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------- |
| `alt` | `string` | | `true` | Specifies a text value explaining the nature of the image for users of assistive technology. |
| `animate` | `AnimateProps` | `undefined` | `false` | When wrapped in an `<AnimationProvider>`, applies an animation preset. |
| `borderRadius` | <PropTableValues values={[...ImageBorderRadiusOptions]} commaSeparated /> | `undefined` | `false` | Applies a system-level border radius value to the Image. |

0 comments on commit e20b2e2

Please sign in to comment.