Skip to content

Commit 0629f03

Browse files
joshfarrantjoshfarrant
committed
update docs
1 parent 301179b commit 0629f03

File tree

1 file changed

+67
-69
lines changed

1 file changed

+67
-69
lines changed

‎apps/docs/content/components/Image/react.mdx

+67-69
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ description: Use the image component to display a graphical representation.
77
---
88

99
import ComponentLayout from '../../../src/layouts/component-layout'
10+
import {PropTableValues} from '../../../src/components'
1011
import {ImageBorderRadiusOptions} from '@primer/react-brand'
11-
export default ComponentLayout
1212

1313
import {Label} from '@primer/react'
14+
export default ComponentLayout
1415

1516
```js
1617
import {Image} from '@primer/react-brand'
@@ -20,7 +21,7 @@ import {Image} from '@primer/react-brand'
2021

2122
### Default
2223

23-
This component uses the `img` element by default.
24+
This component renders an `img` element.
2425

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

3233
### Picture
3334

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

3637
```jsx live
37-
<Image
38-
as="picture"
39-
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
40-
alt="placeholder, blank area with an off-white background color"
41-
/>
38+
<picture>
39+
<Image
40+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
41+
alt="placeholder, blank area with an off-white background color"
42+
/>
43+
</picture>
4244
```
4345

4446
### Picture with sources
4547

46-
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`.
48+
Add `source` elements as siblings to the `Image` component inside the `picture` element.
4749

4850
```jsx live
49-
<Image
50-
as="picture"
51-
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
52-
alt="placeholder, blank area with an off-white background color"
53-
sources={[
54-
{
55-
srcset: 'https://via.placeholder.com/600x400/d3d9df/d3d9df.png',
56-
media: '(min-width: 600px)',
57-
},
58-
{
59-
srcset: 'https://via.placeholder.com/900x600/d3d9df/d3d9df.png',
60-
media: '(min-width: 900px)',
61-
},
62-
]}
63-
/>
51+
<picture>
52+
<source
53+
srcset="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
54+
media="(min-width: 600px)"
55+
/>
56+
<source
57+
srcset="https://via.placeholder.com/900x600/d3d9df/d3d9df.png"
58+
media="(min-width: 900px)"
59+
/>
60+
<Image
61+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
62+
alt="placeholder, blank area with an off-white background color"
63+
/>
64+
</picture>
6465
```
6566

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

7879
### Aspect ratio
7980

80-
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.
81-
82-
```jsx live
83-
<Image
84-
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
85-
alt="placeholder, blank area with an off-white background color"
86-
aspectRatio="16:9"
87-
/>
88-
```
89-
90-
### Height
91-
92-
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.
81+
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.
9382

9483
```jsx live
95-
<Image
96-
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
97-
alt="placeholder, blank area with an off-white background color"
98-
height={200}
99-
aspectRatio="16:9"
100-
/>
84+
<Stack direction="horizontal" alignItems="flex-start">
85+
<Image
86+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
87+
alt="placeholder, blank area with an off-white background color"
88+
height={100}
89+
style={{
90+
aspectRatio: '1/1',
91+
}}
92+
/>
93+
<Image
94+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
95+
alt="placeholder, blank area with an off-white background color"
96+
height={100}
97+
style={{
98+
aspectRatio: '4/3',
99+
}}
100+
/>
101+
<Image
102+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
103+
alt="placeholder, blank area with an off-white background color"
104+
height={100}
105+
style={{
106+
aspectRatio: '16/10',
107+
}}
108+
/>
109+
<Image
110+
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
111+
alt="placeholder, blank area with an off-white background color"
112+
height={100}
113+
style={{
114+
aspectRatio: '16/9',
115+
}}
116+
/>
117+
</Stack>
101118
```
102119

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

147-
### Width
148-
149-
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.
150-
151-
```jsx live
152-
<Image
153-
src="https://via.placeholder.com/600x400/d3d9df/d3d9df.png"
154-
alt="placeholder, blank area with an off-white background color"
155-
width={200}
156-
aspectRatio="16:9"
157-
/>
158-
```
159-
160164
## Component props
161165

162166
### Image <Label>Required</Label>
163167

164-
| name | type | default | required | description |
165-
| -------------- | -------------------------------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166-
| `src` | `string` | | `true` | Specifies the path to the image |
167-
| `alt` | `string` | | `true` | Specifies a text value explaining the nature of the image for users of assistive technology |
168-
| `as` | `img`, `picture` | `img` | `false` | Specification to create a picture component |
169-
| `sources` | `{srcset: string, media: string}[]` | | `false` | When picture is specified in the `as` prop sources allows you to set the source elements. |
170-
| `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. |
171-
| `borderRadius` | <PropTableValues values={[...ImageBorderRadiusOptions]} commaSeparated /> | `undefined` | `false` | Applies a system-level border radius value to the Image. |
172-
| `height` | `number` | | `false` | The height of the image element or its container if it has an aspect ratio |
173-
| `width` | `number` | | `false` | The width of the image element or its container if it has an aspect ratio |
174-
| `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. |
175-
| `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. |
176-
| `className` | `string` | | `false` | Sets a custom CSS class |
168+
All standard `img` attributes are supported as defined by `React.ImgHTMLAttributes<HTMLImageElement>` with the following additions.
169+
170+
| name | type | default | required | description |
171+
| -------------- | -------------------------------------------------------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------- |
172+
| `alt` | `string` | | `true` | Specifies a text value explaining the nature of the image for users of assistive technology. |
173+
| `animate` | `AnimateProps` | `undefined` | `false` | When wrapped in an `<AnimationProvider>`, applies an animation preset. |
174+
| `borderRadius` | <PropTableValues values={[...ImageBorderRadiusOptions]} commaSeparated /> | `undefined` | `false` | Applies a system-level border radius value to the Image. |

0 commit comments

Comments
 (0)