Skip to content

Commit 45ea7c1

Browse files
jscottsmithjscottsmith
committed
docs: ParallaxBanner documentation updates
1 parent 243739f commit 45ea7c1

File tree

1 file changed

+54
-29
lines changed

1 file changed

+54
-29
lines changed

‎documentation/docs/usage/components/parallax-banner-component.md

Lines changed: 54 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,13 @@ sidebar_position: 3
44

55
# ParallaxBanner
66

7-
Component that utilizes `<Parallax>` components to achieve a parallaxing banner effect. Allows a single or multiple images to be parallaxed at different rates within the banner area.
7+
Component that sets up layers of `useParallax` elements to achieve a parallaxing banner. Enables the layering of images, or custom markup, with scroll effects in a container that hides overflow.
88

9-
## Basic Example
9+
### Working Demos
10+
11+
See some example [code with demos](/docs/examples/banners).
12+
13+
## Examples
1014

1115
Use the `layers` to supply a `speed` and `image` to your banner. In this case, it will create a banner using a single image, that moves slower than the rate of scroll, and the edges of the image will never be visible.
1216

@@ -18,19 +22,17 @@ Use the `layers` to supply a `speed` and `image` to your banner. In this case, i
1822
speed: -20,
1923
},
2024
]}
21-
style={{
22-
height: '500px',
23-
}}
25+
style={{ aspectRatio: '2 / 1' }}
2426
/>
2527
```
2628

2729
:::caution
2830

29-
You **must** add a `height` value either as a `style` or through a `className` otherwise the banner will have no height and be hidden.
31+
You **must** define a style that gives the root `<div>` a `height` value otherwise the banner will have no height and be hidden. This can be through a `style`, through a `className`, or other method of styling.
3032

3133
:::
3234

33-
## Multiple Layers
35+
### Multiple Layers
3436

3537
Supply the `layers` prop with additional configuration for more images. Each layer can contain unique configurations.
3638

@@ -46,15 +48,19 @@ Supply the `layers` prop with additional configuration for more images. Each lay
4648
speed: -10,
4749
},
4850
]}
49-
style={{
50-
height: '500px',
51-
}}
51+
style={{ aspectRatio: '2 / 1' }}
5252
/>
5353
```
5454

55-
## Customized Layers
55+
:::caution
56+
57+
**Layer order matters.** First element in the the array will appear on the bottom of the stacking context; last layer of the array will appear on top.
58+
59+
:::
60+
61+
### Customized Layers
5662

57-
Supply the `layers` prop with [additional configuration](#banner-layers-prop) for more images. Each layer can contain unique configurations.
63+
You can pass your own markup or components to the `children` property of a `layer`.
5864

5965
```jsx
6066
<ParallaxBanner
@@ -68,31 +74,50 @@ Supply the `layers` prop with [additional configuration](#banner-layers-prop) fo
6874
speed: -10,
6975
},
7076
]}
71-
style={{
72-
height: '500px',
73-
}}
77+
style={{ aspectRatio: '2 / 1' }}
7478
/>
7579
```
7680

7781
## Props
7882

7983
The following are all props that can be passed to the `<ParallaxBanner>` component:
8084

81-
| Name | Type | Default | Description |
82-
| ------------- | :-------: | :------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
83-
| **className** | `string` | | Optionally pass additional class names to be added to the outermost parallax banner element. |
84-
| **disabled** | `boolean` | `false` | Determines if the internal parallax layers will have offsets applied. |
85-
| **layers** | `array` | | A required `array` of `objects` with layer properties: `[{ amount: 0.1, image: 'foo.jpg' }]`. [See layers prop below](#banner-layers-prop) |
86-
| **style** | `object` | | Optionally pass a style object to be added to the outermost parallax banner element. |
85+
| Name | Type | Description |
86+
| ------------ | :--------------: | ------------------------------------------------------------------------------------------------------------------------------------------- |
87+
| **disabled** | `boolean` | Disables _all_ parallax layers when enabled. |
88+
| **layers** | `array` | An `array` of `objects` with layer properties: [see layer props below](/docs/usage/components/parallax-banner-component#banner-layers-prop) |
89+
| `...rest` | `HTMLDivElement` | All other properties are spread to the `<div>`. |
90+
91+
:::info
92+
93+
All other props are defined on the root `div` element.
94+
95+
```jsx
96+
<ParallaxBanner className="custom-class" id="hero-banner" />
97+
```
98+
99+
:::
87100

88101
## Banner Layers Prop
89102

90-
The `layers` prop takes an array of objects that will represent each image (or custom children) of the parallax banner. The following properties describe a layer object:
103+
The `layers` prop takes an array of objects that represent each image (or custom children) of the parallax banner. The following properties describe a layer object:
104+
105+
| Name | Type | Default | Description |
106+
| ------------ | :---------------------: | :------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107+
| **children** | `ReactElement` | | Custom layer children provided as a React element, for example `<Video />` |
108+
| **expanded** | `boolean` | `true` | Indicate if the layer should be expanded with negative top/bottom margins so the edges will never be visible. |
109+
| **image** | `string` | | Image source that will be applied as a CSS `background-image` on the layer set to `cover`. |
110+
| `...rest` | `ParallaxElementConfig` | | All known parallax props will be passed to `useParallax`. [See all the parallax props](https://parallax-controller.vercel.app/docs/usage/props) that this hook will accept. All other properties are spread to the `<div>` representing the layer. |
91111

92-
| Name | Type | Default | Description |
93-
| ------------ | :------------: | :------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
94-
| **speed** | `number` | | A value from `-1` to `1` that represents the vertical offset to be applied to the current layer, `0.1` would equal a `10%` offset on the top and bottom. |
95-
| **children** | `ReactElement` | | Custom layer children provided as a React element, for example `<Video />` |
96-
| **expanded** | `boolean` | `true` | Indicate if the layer should be expanded with negative top/bottom margins so the edges will never be visible. |
97-
| **image** | `string` | | Image source that will be applied as a CSS background image on the layer. |
98-
| **props** | `object` | | Props to apply to the layer element. Example: `{ props: style: { background: 'red' }}` |
112+
```jsx
113+
<ParallaxBanner
114+
layers={[
115+
{
116+
children: <div />,
117+
speed: -10,
118+
scale: [1, 1.2],
119+
opacity: [0.9, 1],
120+
},
121+
]}
122+
/>
123+
```

0 commit comments

Comments
 (0)