Skip to content

Commit e262e78

Browse files
stampaaaronstampaaaron
committed
docs: enhance readme documentation
1 parent 32a1671 commit e262e78

File tree

2 files changed

+122
-11
lines changed

2 files changed

+122
-11
lines changed

‎README.md

Lines changed: 122 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
11
# react-alternating-timeline
22

3-
A compact react timeline component.
3+
A compact, masonry style alternating timeline react component which is fully customizable.
44

5-
## Getting started
5+
![Demonstration](./docs/demonstration.jpg)
6+
7+
## Features
8+
9+
- 🎛️ Customize everything.
10+
- 🎨 Consistent ([BEM](https://getbem.com)) class naming for easy styling with CSS, emotion...
11+
- ⏰ Date formatting using [date-fns](date-fns.org) standard.
12+
- ⚖️ Alternating, left or right positioning.
13+
- 🖼️ Render images and custom content.
14+
- 🪄 Built with Typescript.
15+
16+
## Installation
617

718
Add the package with the package manager via NPMs or GitHubs registry of choice to your project:
819

@@ -11,13 +22,113 @@ Add the package with the package manager via NPMs or GitHubs registry of choice
1122
- **pnpm**: `pnpm add react-alternating-timeline`
1223
- **npx**: `npx -p react-alternating-timeline`
1324

14-
## Resources
25+
## Usage
26+
27+
```ts
28+
import { Timeline, TimelineItemsProps } from 'react-alternating-timeline';
29+
30+
const items: TimelineItemsProps = [
31+
{
32+
key: 'first',
33+
date: new Date(),
34+
title: 'Special event!',
35+
},
36+
{
37+
key: 'second',
38+
date: new Date(),
39+
title: 'Event',
40+
children: <img src="./test.jpg" alt="test" />,
41+
},
42+
...
43+
];
44+
45+
<Timeline items={items} />;
46+
```
47+
48+
## API
49+
50+
The available properties of the `Timeline` component:
51+
52+
| Property | Type | Description | Default |
53+
| :---------------------- | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |
54+
| `items` | [`TimelineItemsProps`](#timelineitemsprops) | Array of timeline items | |
55+
| `positioning?` | `'alternating' \| 'left' \| 'right'` | How the items should be positioned relative to the timeline | `'alternating'` |
56+
| `gap?` | `number` | The horizontal gap between timeline items | 50 (`px`) |
57+
| `offset?` | `{ left?: number; right?: number } \| number` | Offset left or right items from the top (default offset when passing just a `number`: `right`) | 50 (`px`) |
58+
| `minMarkerGap?` | `number` | The minimum gap markers will have between each other | 50 (`px`) |
59+
| `defaultPointerOffset?` | `number` | The regular top offset pointers have to their item card | 40 (`px`) |
60+
| `dateLocal?` | `Local` | Date locale | |
61+
| `dateFormat?` | `string` | Specific date format according to date-fns [specification](https://date-fns.org/v2.29.3/docs/format). Ignored when passing a `string` as date | `'P'` |
62+
| `customMarker?` | `ReactElement` | Custom maker element replacing the default | |
63+
| `customPointer?` | `ReactElement` | Custom pointer element replacing the default | |
64+
| `styleConfig?` | [`StyleConfig`](#styleconfig) | Style config object for customizing timeline by setting css custom properties | |
65+
| `className?` | `string` | Additional class name | |
66+
67+
### TimelineItemsProps
68+
69+
An array of the following properties:
70+
71+
| Property | Type | Description |
72+
| :--------------- | :------------------ | :------------------------------------------------------------------------------- |
73+
| `key` | `Key` | Unique key for each item |
74+
| `title?` | `string` | Optional title paragraph displayed bold |
75+
| `date` | `Date \| string` | Date either being formatted according to provided format or passed as a `string` |
76+
| `children?` | `ReactNode` | Pass custom content as `children` to the component |
77+
| `dateFormat?` | `string` | Overwriting `dateFormat` property of parent `Timeline` |
78+
| `dateLocale?` | `string` | Overwriting `dateLocale` property of parent `Timeline` |
79+
| `customMarker?` | `ReactElement` | Overwriting `customMarker` property of parent `Timeline` |
80+
| `customPointer?` | `ReactElement` | Overwriting `customPointer` property of parent `Timeline` |
81+
82+
### StyleConfig
83+
84+
The style can either be passed as a javascript object...
85+
86+
```ts
87+
{
88+
line?: {
89+
width?: string;
90+
color?: string;
91+
};
92+
marker?: {
93+
size?: string;
94+
color?: string;
95+
radius?: string;
96+
};
97+
pointer?: {
98+
height?: string;
99+
width?: string;
100+
};
101+
card?: {
102+
background?: string;
103+
radius?: string;
104+
offset?: string;
105+
shadow?: string;
106+
padding?: string;
107+
};
108+
};
109+
```
110+
111+
...or the custom properties can be set directly in css
112+
113+
```css
114+
.timeline {
115+
--line-width: 0.2rem;
116+
--line-color: black;
117+
--marker-size: 1rem;
118+
--marker-color: var(--line-color);
119+
--marker-radius: 50%;
120+
--pointer-height: 2rem;
121+
--pointer-width: 1rem;
122+
--card-background: whitesmoke;
123+
--card-radius: 0.1rem;
124+
--card-offset: 1rem;
125+
--card-shadow: unset;
126+
--card-padding: 1rem;
127+
}
128+
```
129+
130+
(These are the default values)
131+
132+
## Demo
15133

16-
- Articles
17-
- [**Use Vite in Library Mode**](https://vitejs.dev/guide/build.html#library-mode)
18-
- Tools
19-
- [**Vite**](https://vitejs.dev/): Next Generation Frontend Tooling
20-
- [**Vitest**](https://vitest.dev/): A blazing fast unit-test framework powered by Vite.
21-
- [**Vite Plugin dts**](https://github.com/qmhc/vite-plugin-dts): A vite plugin for generating `.d.ts` files.
22-
- [**Storybook**](https://storybook.js.org/): Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation.
23-
- [**Storybook Builder Vite**](https://github.com/storybookjs/builder-vite): An experimental plugin to run and build Storybooks with Vite.
134+
View a full demo of component as storybook: [Storybook](https://openscript-ch.github.io/react-alternating-timeline/) 📗

‎docs/demonstration.jpg

165 KB
Loading

0 commit comments

Comments
 (0)