Skip to content

Commit 0d77749

Browse files
joevilchesjoevilches
authored
Add box shadow documentation (#4464)
* Box sizing documentation * add filter documentation * lint * Reply to comments * box shadow documentation * lint box shadow docs * lint again * remove simple
1 parent 05a5a3b commit 0d77749

File tree

12 files changed

+366
-18
lines changed

12 files changed

+366
-18
lines changed

‎docs/boxshadowvalue.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
id: boxshadowvalue
3+
title: BoxShadowValue Object Type
4+
---
5+
6+
The `BoxShadowValue` object is taken by the [`boxShadow`](./view-style-props.md#boxshadow) style prop. It is comprised of 2-4 lengths, an optional color, and an optional `inset` boolean. These values collectively define the box shadow's color, position, size, and blurriness.
7+
8+
## Example
9+
10+
```js
11+
{
12+
offsetX: 10,
13+
offsetY: -3,
14+
blurRadius: '15px',
15+
spreadDistance: '10px',
16+
color: 'red',
17+
inset: true,
18+
}
19+
```
20+
21+
## Keys and values
22+
23+
### `offsetX`
24+
25+
The offset on the x-axis. This can be positive or negative. A positive value indicates right and negative indicates left.
26+
27+
| Type | Optional |
28+
| ---------------- | -------- |
29+
| number \| string | No |
30+
31+
### `offsetY`
32+
33+
The offset on the y-axis. This can be positive or negative. A positive value indicates up and negative indicates down.
34+
35+
| Type | Optional |
36+
| ---------------- | -------- |
37+
| number \| string | No |
38+
39+
### `blurRadius`
40+
41+
Represents the radius used in the [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur) algorithm. The larger the value the blurrier the shadow is. Only non-negative values are valid. The default is 0.
42+
43+
| Type | Optional |
44+
| --------------- | -------- |
45+
| numer \| string | Yes |
46+
47+
### `spreadDistance`
48+
49+
How much larger or smaller the shadow grows or shrinks. A positive value will grow the shadow, a negative value will shrink the shadow.
50+
51+
| Type | Optional |
52+
| --------------- | -------- |
53+
| numer \| string | Yes |
54+
55+
### `color`
56+
57+
The color of the shadow. The default is `black`.
58+
59+
| Type | Optional |
60+
| -------------------- | -------- |
61+
| [color](./colors.md) | Yes |
62+
63+
### `inset`
64+
65+
Whether the shadow is inset or not. Inset shadows will appear around the inside of the element's border box as opposed to the outside.
66+
67+
| Type | Optional |
68+
| ------- | -------- |
69+
| boolean | Yes |
70+
71+
## Used by
72+
73+
- [`boxShadow`](./view-style-props.md#boxshadow)

‎docs/shadow-props.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,8 +218,32 @@ export default App;
218218

219219
# Reference
220220

221+
There are 3 sets of shadow APIs in React Native:
222+
223+
- `boxShadow`: A View style prop and a spec-compliant implementation of the [web style prop of the same name](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow).
224+
- `dropShadow`: A specific filter function available as part of the [`filter`](./view-style-props#filter) View style prop.
225+
- Various `shadow` props (`shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius`): These map directly to their native counterparts exposed by the platform-level APIs.
226+
227+
The difference between `dropShadow` and `boxShadow` are as follows:
228+
229+
- `dropShadow` exists as part of `filter`, whereas `boxShadow` is a standalone style prop.
230+
- `dropShadow` is an alpha mask, so only pixels with a positive alpha value will "cast" a shadow. `boxShadow` will cast around the border box of the element no matter it's contents (unless it is inset).
231+
- `dropShadow` is only available on Android, `boxShadow` is available on iOS and Android.
232+
- `dropShadow` cannot be inset like `boxShadow`.
233+
- `dropShadow` does not have the `spreadDistance` argument like `boxShadow`.
234+
235+
Both `boxShadow` and `dropShadow` are generally more capable than the `shadow` props. The `shadow` props, however, map to native platform-level APIs, so if you only need a straightforward shadow these props are recommended. Note that only `shadowColor` works on both Android and iOS, all other `shadow` props only work on iOS.
236+
221237
## Props
222238

239+
### `boxShadow`
240+
241+
See [View Style Props](./view-style-props#boxshadow) for documentation.
242+
243+
### `dropShadow` <div class="label android">Android</div>
244+
245+
See [View Style Props](./view-style-props#filter) for documentation.
246+
223247
### `shadowColor`
224248

225249
Sets the drop shadow color.

‎docs/view-style-props.md

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,21 @@ If the rounded border is not visible, try applying `overflow: 'hidden'` as well.
289289
| ------ |
290290
| number |
291291

292+
### `boxShadow`
293+
294+
:::note
295+
`boxShadow` is only available on the [New Architecture](/architecture/landing-page). Outset shadows are only supported on **Android 9+**. Inset shadows are only supported on **Android 10+**.
296+
:::
297+
298+
Adds a shadow effect to an element, with the ability to control the position, color, size, and blurriness of the shadow. This shadow either appears around the outside or inside of the border box of the element, depending on whether or not the shadow is _inset_. This is a spec-compliant implementation of the [web style prop of the same name](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow). Read more about all the arguments available in the [BoxShadowValue](./boxshadowvalue) documentation.
299+
300+
These shadows can be composed together so that a single `boxShadow` can be comprised of multiple different shadows.
301+
302+
`boxShadow` takes either a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow#syntax) or an array of [BoxShadowValue](./boxshadowvalue) objects.
303+
| Type |
304+
| --------------------------- |
305+
| array of BoxShadowValue ojects \| string |
306+
292307
### `cursor` <div class="label ios">iOS</div>
293308

294309
On iOS 17+, Setting to `pointer` allows hover effects when a pointer (such as a trackpad or stylus on iOS, or the users' gaze on visionOS) is over the view.
@@ -311,6 +326,10 @@ Sets the elevation of a view, using Android's underlying [elevation API](https:/
311326

312327
### `filter`
313328

329+
:::note
330+
`filter` is only available on the [New Architecture](/architecture/landing-page)
331+
:::
332+
314333
Adds a graphical filter to the `View`. This filter is comprised of any number of _filter functions_, which each represent some atomic change to the graphical composition of the `View`. The complete list of valid filter functions is defined below. `filter` will apply to descendants of the `View` as well as the `View` itself. `filter` implies `overflow: hidden`, so descendants will be clipped to fit the bounds of the `View`.
315334

316335
The following filter functions work across all platforms:
@@ -329,18 +348,17 @@ The following filter functions work on Android only:
329348
- `blur`: Blurs the `View` with a [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur), where the specified length represents the radius used in the blurring algorithm. Any non-negative DIP value is valid (no percents). The larger the value, the blurrier the result.
330349
- `contrast`: Changes the contrast of the `View`. Takes a non-negative number or percentage.
331350
- `dropShadow`: Adds a shadow around the alpha mask of the `View` (only non-zero alpha pixels in the `View` will cast a shadow). Takes an optional color representing the shadow color, and 2 or 3 lengths. If 2 lengths are specified they are interperted as `offsetX` and `offsetY` which will translate the shadow in the X and Y dimensions respectfully. If a 3rd length is given it is interpreted as the standard deviation of the Guassian blur used on the shadow - so a larger value will blur the shadow more. Read more about the arguments in [DropShadowValue](./dropshadowvalue.md).
332-
333-
:::note
334-
Outset shadows are only supported on **Android 9+**. Inset shadows are only supported on **Android 10+**.
335-
:::
336-
337351
- `grayscale`: Converts the `View` to [grayscale](https://en.wikipedia.org/wiki/Grayscale) by the specified amount. Takes a non-negative number or percentage, where `1` or `100%` represents complete grayscale.
338352
- `hueRotate`: Changes the [hue](https://en.wikipedia.org/wiki/Hue) of the View. The argument of this function defines the angle of a color wheel around which the hue will be rotated, so e.g., `360deg` would have no effect. This angle can have either `deg` or `rad` units.
339353
- `invert`: Inverts the colors in the `View`. Takes a non-negative number or percentage, where `1` or `100%` represents complete inversion.
340354
- `sepia`: Converts the `View` to [sepia](<https://en.wikipedia.org/wiki/Sepia_(color)>). Takes a non-negative number or percentage, where `1` or `100%` represents complete sepia.
341355
- `saturate`: Changes the [saturation](https://en.wikipedia.org/wiki/Colorfulness) of the `View`. Takes a non-negative number or percentage.
342356

343-
`filter` takes either an array of objects comprising of the above filter functions or a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
357+
:::note
358+
`blur` and `dropShadow` are only supported on **Android 12+**
359+
:::
360+
361+
`filter` takes either an array of objects comprising of the above filter functions or a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/filter#syntax).
344362
| Type |
345363
| ------ |
346364
| array of objects: `{brightness: number\|string}`, `{opacity: number\|string}`, `{blur: number\|string}`, `{contrast: number\|string}`, `{dropShadow: DropShadowValue\|string}`, `{grayscale: number\|string}`, `{hueRotate: number\|string}`, `{invert: number\|string}`, `{sepia: number\|string}`, `{saturate: number\|string}` or string|

‎website/sidebars.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,7 @@ export default {
298298
'view-style-props',
299299
],
300300
'Object Types': [
301+
'boxshadowvalue',
301302
'dropshadowvalue',
302303
'layoutevent',
303304
'pressevent',

‎website/versioned_docs/version-0.76/boxshadowvalue.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
id: boxshadowvalue
3+
title: BoxShadowValue Object Type
4+
---
5+
6+
The `BoxShadowValue` object is taken by the [`boxShadow`](./view-style-props.md#boxshadow) style prop. It is comprised of 2-4 lengths, an optional color, and an optional `inset` boolean. These values collectively define the box shadow's color, position, size, and blurriness.
7+
8+
## Example
9+
10+
```js
11+
{
12+
offsetX: 10,
13+
offsetY: -3,
14+
blurRadius: '15px',
15+
spreadDistance: '10px',
16+
color: 'red',
17+
inset: true,
18+
}
19+
```
20+
21+
## Keys and values
22+
23+
### `offsetX`
24+
25+
The offset on the x-axis. This can be positive or negative. A positive value indicates right and negative indicates left.
26+
27+
| Type | Optional |
28+
| ---------------- | -------- |
29+
| number \| string | No |
30+
31+
### `offsetY`
32+
33+
The offset on the y-axis. This can be positive or negative. A positive value indicates up and negative indicates down.
34+
35+
| Type | Optional |
36+
| ---------------- | -------- |
37+
| number \| string | No |
38+
39+
### `blurRadius`
40+
41+
Represents the radius used in the [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur) algorithm. The larger the value the blurrier the shadow is. Only non-negative values are valid. The default is 0.
42+
43+
| Type | Optional |
44+
| --------------- | -------- |
45+
| numer \| string | Yes |
46+
47+
### `spreadDistance`
48+
49+
How much larger or smaller the shadow grows or shrinks. A positive value will grow the shadow, a negative value will shrink the shadow.
50+
51+
| Type | Optional |
52+
| --------------- | -------- |
53+
| numer \| string | Yes |
54+
55+
### `color`
56+
57+
The color of the shadow. The default is `black`.
58+
59+
| Type | Optional |
60+
| -------------------- | -------- |
61+
| [color](./colors.md) | Yes |
62+
63+
### `inset`
64+
65+
Whether the shadow is inset or not. Inset shadows will appear around the inside of the element's border box as opposed to the outside.
66+
67+
| Type | Optional |
68+
| ------- | -------- |
69+
| boolean | Yes |
70+
71+
## Used by
72+
73+
- [`boxShadow`](./view-style-props.md#boxshadow)

‎website/versioned_docs/version-0.76/shadow-props.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,8 +218,32 @@ export default App;
218218

219219
# Reference
220220

221+
There are 3 sets of shadow APIs in React Native:
222+
223+
- `boxShadow`: A View style prop and a spec-compliant implementation of the [web style prop of the same name](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow).
224+
- `dropShadow`: A specific filter function available as part of the [`filter`](./view-style-props#filter) View style prop.
225+
- Various `shadow` props (`shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius`): These map directly to their native counterparts exposed by the platform-level APIs.
226+
227+
The difference between `dropShadow` and `boxShadow` are as follows:
228+
229+
- `dropShadow` exists as part of `filter`, whereas `boxShadow` is a standalone style prop.
230+
- `dropShadow` is an alpha mask, so only pixels with a positive alpha value will "cast" a shadow. `boxShadow` will cast around the border box of the element no matter it's contents (unless it is inset).
231+
- `dropShadow` is only available on Android, `boxShadow` is available on iOS and Android.
232+
- `dropShadow` cannot be inset like `boxShadow`.
233+
- `dropShadow` does not have the `spreadDistance` argument like `boxShadow`.
234+
235+
Both `boxShadow` and `dropShadow` are generally more capable than the `shadow` props. The `shadow` props, however, map to native platform-level APIs, so if you only need a straightforward shadow these props are recommended. Note that only `shadowColor` works on both Android and iOS, all other `shadow` props only work on iOS.
236+
221237
## Props
222238

239+
### `boxShadow`
240+
241+
See [View Style Props](./view-style-props#boxshadow) for documentation.
242+
243+
### `dropShadow` <div class="label android">Android</div>
244+
245+
See [View Style Props](./view-style-props#filter) for documentation.
246+
223247
### `shadowColor`
224248

225249
Sets the drop shadow color.

‎website/versioned_docs/version-0.76/view-style-props.md

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,21 @@ If the rounded border is not visible, try applying `overflow: 'hidden'` as well.
289289
| ------ |
290290
| number |
291291

292+
### `boxShadow`
293+
294+
:::note
295+
`boxShadow` is only available on the [New Architecture](/architecture/landing-page). Outset shadows are only supported on **Android 9+**. Inset shadows are only supported on **Android 10+**.
296+
:::
297+
298+
Adds a shadow effect to an element, with the ability to control the position, color, size, and blurriness of the shadow. This shadow either appears around the outside or inside of the border box of the element, depending on whether or not the shadow is _inset_. This is a spec-compliant implementation of the [web style prop of the same name](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow). Read more about all the arguments available in the [BoxShadowValue](./boxshadowvalue) documentation.
299+
300+
These shadows can be composed together so that a single `boxShadow` can be comprised of multiple different shadows.
301+
302+
`boxShadow` takes either a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow#syntax) or an array of [BoxShadowValue](./boxshadowvalue) objects.
303+
| Type |
304+
| --------------------------- |
305+
| array of BoxShadowValue ojects \| string |
306+
292307
### `cursor` <div class="label ios">iOS</div>
293308

294309
On iOS 17+, Setting to `pointer` allows hover effects when a pointer (such as a trackpad or stylus on iOS, or the users' gaze on visionOS) is over the view.
@@ -311,6 +326,10 @@ Sets the elevation of a view, using Android's underlying [elevation API](https:/
311326

312327
### `filter`
313328

329+
:::note
330+
`filter` is only available on the [New Architecture](/architecture/landing-page)
331+
:::
332+
314333
Adds a graphical filter to the `View`. This filter is comprised of any number of _filter functions_, which each represent some atomic change to the graphical composition of the `View`. The complete list of valid filter functions is defined below. `filter` will apply to descendants of the `View` as well as the `View` itself. `filter` implies `overflow: hidden`, so descendants will be clipped to fit the bounds of the `View`.
315334

316335
The following filter functions work across all platforms:
@@ -328,19 +347,18 @@ The following filter functions work on Android only:
328347

329348
- `blur`: Blurs the `View` with a [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur), where the specified length represents the radius used in the blurring algorithm. Any non-negative DIP value is valid (no percents). The larger the value, the blurrier the result.
330349
- `contrast`: Changes the contrast of the `View`. Takes a non-negative number or percentage.
331-
- `dropShadow`: Adds a shadow around the alpha mask of the `View` (only non-zero alpha pixels in the `View` will cast a shadow). Takes an optional color representing the shadow color, and 2 or 3 lengths. If 2 lengths are specified they are interperted as `offsetX` and `offsetY` which will translate the shadow in the X and Y dimensions respectfully. If a 3rd length is given it is interpreted as the standard deviation of the Guassian blur used on the shadow - so a larger value will blur the shadow more. Read more about the arguments in [DropShadowValue](./dropshadowvalue).
332-
333-
:::note
334-
Outset shadows are only supported on **Android 9+**. Inset shadows are only supported on **Android 10+**.
335-
:::
336-
350+
- `dropShadow`: Adds a shadow around the alpha mask of the `View` (only non-zero alpha pixels in the `View` will cast a shadow). Takes an optional color representing the shadow color, and 2 or 3 lengths. If 2 lengths are specified they are interperted as `offsetX` and `offsetY` which will translate the shadow in the X and Y dimensions respectfully. If a 3rd length is given it is interpreted as the standard deviation of the Guassian blur used on the shadow - so a larger value will blur the shadow more. Read more about the arguments in [DropShadowValue](./dropshadowvalue.md).
337351
- `grayscale`: Converts the `View` to [grayscale](https://en.wikipedia.org/wiki/Grayscale) by the specified amount. Takes a non-negative number or percentage, where `1` or `100%` represents complete grayscale.
338352
- `hueRotate`: Changes the [hue](https://en.wikipedia.org/wiki/Hue) of the View. The argument of this function defines the angle of a color wheel around which the hue will be rotated, so e.g., `360deg` would have no effect. This angle can have either `deg` or `rad` units.
339353
- `invert`: Inverts the colors in the `View`. Takes a non-negative number or percentage, where `1` or `100%` represents complete inversion.
340354
- `sepia`: Converts the `View` to [sepia](<https://en.wikipedia.org/wiki/Sepia_(color)>). Takes a non-negative number or percentage, where `1` or `100%` represents complete sepia.
341355
- `saturate`: Changes the [saturation](https://en.wikipedia.org/wiki/Colorfulness) of the `View`. Takes a non-negative number or percentage.
342356

343-
`filter` takes either an array of objects comprising of the above filter functions or a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
357+
:::note
358+
`blur` and `dropShadow` are only supported on **Android 12+**
359+
:::
360+
361+
`filter` takes either an array of objects comprising of the above filter functions or a string which mimics the [web syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/filter#syntax).
344362
| Type |
345363
| ------ |
346364
| array of objects: `{brightness: number\|string}`, `{opacity: number\|string}`, `{blur: number\|string}`, `{contrast: number\|string}`, `{dropShadow: DropShadowValue\|string}`, `{grayscale: number\|string}`, `{hueRotate: number\|string}`, `{invert: number\|string}`, `{sepia: number\|string}`, `{saturate: number\|string}` or string|

0 commit comments

Comments
 (0)