Skip to content

Commit 69f5c54

Browse files
stampaaaronstampaaaron
committed
docs: enhance styling documentation
1 parent 6a3090f commit 69f5c54

File tree

1 file changed

+58
-29
lines changed

1 file changed

+58
-29
lines changed

‎README.md

Lines changed: 58 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# react-alternating-timeline
22

3-
A compact, masonry style alternating timeline react component which is fully customizable.
3+
A simple and compact, true masonry style alternating timeline react component which is fully customizable and free stylable.
44

55
![Demonstration](./docs/demonstration.jpg)
66

@@ -57,7 +57,7 @@ The available properties of the `Timeline` component:
5757
| `formatDate?` | `(date: Date) => string` | Callback to format date | |
5858
| `customMarker?` | `ReactElement` | Custom maker element replacing the default | |
5959
| `customPointer?` | `ReactElement` | Custom pointer element replacing the default | |
60-
| `styleConfig?` | [`StyleConfig`](#styleconfig) | Style config object for customizing timeline by setting css custom properties | |
60+
| `styleConfig?` | [`StyleConfig`](#styling) | Style config object for customizing timeline by setting css custom properties | |
6161
| `className?` | `string` | Additional class name | |
6262

6363
### TimelineItemsProps
@@ -74,65 +74,94 @@ An array of the following properties:
7474
| `customMarker?` | `ReactElement` | Overwriting `customMarker` property of parent `Timeline` |
7575
| `customPointer?` | `ReactElement` | Overwriting `customPointer` property of parent `Timeline` |
7676

77-
### StyleConfig
77+
## Styling
7878

79-
The style can either be passed as a javascript object...
79+
The style can either be passed as an object through the `styleConfig` property...
8080

8181
```ts
8282
{
8383
line?: {
84-
width?: string;
85-
color?: string;
84+
width?: CSSProperties['width'];
85+
color?: CSSProperties['backgroundColor'];
86+
overhang?: CSSProperties['paddingBlock'];
8687
};
87-
gap?: string;
88-
offset?: {
89-
left?: string;
90-
right?: string;
88+
item?: {
89+
gap?: CSSProperties['gap'];
90+
startOffset?: {
91+
left?: CSSProperties['marginTop'];
92+
right?: CSSProperties['marginTop'];
93+
};
9194
};
9295
marker?: {
93-
size?: string;
94-
color?: string;
95-
radius?: string;
96+
size?: CSSProperties['width'];
97+
color?: CSSProperties['backgroundColor'];
98+
radius?: CSSProperties['borderRadius'];
9699
};
97100
pointer?: {
98-
height?: string;
99-
width?: string;
100-
offset?: string;
101+
height?: CSSProperties['height'];
102+
width?: CSSProperties['width'];
103+
minOffset?: CSSProperties['marginTop'];
101104
};
102105
card?: {
103-
background?: string;
104-
radius?: string;
105-
offset?: string;
106-
shadow?: string;
107-
padding?: string;
106+
background?: CSSProperties['backgroundColor'];
107+
radius?: CSSProperties['borderRadius'];
108+
shadow?: CSSProperties['boxShadow'];
109+
padding?: CSSProperties['padding'];
110+
offset?: CSSProperties['gap'];
108111
};
109-
};
112+
}
110113
```
111114

112-
...or the custom properties can be set directly in css
115+
...or can be set as custom properties directly in css
113116

114117
```css
115118
.timeline {
116119
--line-width: 0.2rem;
117120
--line-color: black;
121+
--line-overhang: 1rem;
122+
--item-gap: 1rem;
123+
--item-start-offset-left: 0;
124+
--item-start-offset-right: 5rem;
118125
--marker-size: 1rem;
119126
--marker-color: var(--line-color);
120127
--marker-radius: 50%;
121128
--pointer-height: 2rem;
122129
--pointer-width: 1rem;
123-
--pointer-offset: 5rem;
130+
--pointer-min-offset: 5rem;
124131
--card-background: whitesmoke;
125132
--card-radius: 0.1rem;
126-
--card-offset: 1rem;
127133
--card-shadow: unset;
128134
--card-padding: 1rem;
129-
--gap: 1rem;
130-
--offset-left: 0;
131-
--offset-right: 5rem;
135+
--card-offset: 1rem;
132136
}
133137
```
134138

135-
(These are the default values)
139+
### StyleConfig
140+
141+
| Name | Description | Default |
142+
| :------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------ |
143+
| **Line** | The line the timeline items are place around/beside | |
144+
| – `line-width` | Width of the line | `0.2rem` |
145+
| – `line-color` | Color of the line | `black` |
146+
| – `line-overhang` | How much the line should overhang the beginning and end of the timeline component | `1rem` |
147+
| **Item** | The timeline item as a whole, including the card, pointer and marker | |
148+
| – `item-gap` | The vertical space between the items | `1rem` |
149+
| – `item-start-offset-left` | How much the items on the left side should be offset from the top | `0` |
150+
| – `item-start-offset-left` | How much the items on the right side should be offset from the top | `5rem` |
151+
| **Marker** | The markers on the line which marks the chronological order of the timeline items | `1rem` |
152+
| – `marker-size` | Size of the default marker | `1rem` |
153+
| – `marker-color` | Color of the default marker | `line-color` |
154+
| – `marker-radius` | Border radius (roundness) of the marker edges | `50%` (round) |
155+
| **Pointer** | The pointers pointing from the item cards to the markers on the line | |
156+
| – `pointer-height` | Height of the default pointer | `2rem` |
157+
| – `pointer-width` | Width of the default pointer | `1rem` |
158+
| – `pointer-min-offset` | Minimum offset of the pointer to the top of the card. The actual offset depends on the `minMarkerGap` property | `5rem` |
159+
| **Card** | The cards in which the timeline item content is displayed | |
160+
| – `card-background` | Background color of the card | `whitesmoke` |
161+
| – `card-radius` | Border radius of the card edges | `0.1rem` |
162+
| – `card-shadow` | Configure drop shadow of the card | `unset` |
163+
| – `card-padding` | Padding of the card content | `1rem` |
164+
| – `card-offset` | Space between the card and the timeline line | `1rem` |
136165

137166
## Demo
138167

0 commit comments

Comments
 (0)