Timeline

An unstyled timeline component for visualizing sequential events with full control over layout and styling.

Build fully custom timelines and event sequences with complete control over layout and styling.

15/10/2026 10:30

Ordered

15/10/2026 14:00

Processing

15/10/2026 16:15

Shipped

16/10/2026 10:00

Delivered

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Timeline with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Event, Separator, Marker, Connector, Content, Opposite
Five alignment modes for flexible content placement
Vertical and horizontal orientation support
Opposite-side content for metadata like dates or timestamps

Usage#

import { Timeline } from 'primereact/timeline';

<Timeline.Root>
    <Timeline.Event>
        <Timeline.Opposite></Timeline.Opposite>
        <Timeline.Separator>
            <Timeline.Marker />
            <Timeline.Connector />
        </Timeline.Separator>
        <Timeline.Content></Timeline.Content>
    </Timeline.Event>
</Timeline.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Timeline.Root as="section"></Timeline.Root>
<Timeline.Content as="article"></Timeline.Content>

Default elements: Root=div, Event=div, Separator=div, Marker=div, Connector=div, Content=div, Opposite=div.

Render Function Children#

Root accepts a render function as children, providing access to the component instance.

<Timeline.Root align="alternate">{(instance) => <span>Align: {instance.props.align}</span>}</Timeline.Root>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

15/10/2026 10:30

Ordered

15/10/2026 14:00

Processing

15/10/2026 16:15

Shipped

16/10/2026 10:00

Delivered

/* Select a part to see its CSS selector for custom styling */

API#

TimelineRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`align`	`"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"alternate"`	`left`
Alignment of the content.
`orientation`	`"horizontal"` \| `"vertical"`	`vertical`
Specifies the orientation, valid values are 'horizontal' and 'vertical'.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"root"`
`data-align`	Current alignment value
`data-orientation`	Current orientation value

Defines passthrough(pt) options of Timeline component.

label	type	description
root	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
event	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the event's DOM element.
content	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the content's DOM element.
opposite	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the opposite's DOM element.
separator	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the separator's DOM element.
marker	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the marker's DOM element.
connector	TimelineRootPassThroughType<InputHTMLAttributes<HTMLDivElement>>	Used to pass attributes to the connector's DOM element.

TimelineEvent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineEventInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineEventInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineEventInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineEventPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineEventInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"event"`

Defines passthrough(pt) options of TimelineEvent component.

label	type	description
root	TimelineEventPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

TimelineSeparator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineSeparatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineSeparatorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineSeparatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineSeparatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineSeparatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"separator"`

Defines passthrough(pt) options of TimelineSeparator component.

label	type	description
root	TimelineSeparatorPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

TimelineMarker#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineMarkerInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineMarkerInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineMarkerInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineMarkerPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineMarkerInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"marker"`

Defines passthrough(pt) options of TimelineMarker component.

label	type	description
root	TimelineMarkerPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

TimelineConnector#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineConnectorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineConnectorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineConnectorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineConnectorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineConnectorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"connector"`

Defines passthrough(pt) options of TimelineConnector component.

label	type	description
root	TimelineConnectorPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

TimelineContent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineContentInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineContentInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineContentInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineContentPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineContentInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"content"`

Defines passthrough(pt) options of TimelineContent component.

label	type	description
root	TimelineContentPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

TimelineOpposite#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: TimelineOppositeInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: TimelineOppositeInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`TimelineOppositeInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<TimelineOppositePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: TimelineOppositeInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"timeline"`
`data-part`	`"opposite"`

Defines passthrough(pt) options of TimelineOpposite component.

label	type	description
root	TimelineOppositePassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Timeline uses semantic containers for event structure. Add aria-label on the root to describe the timeline purpose. Event content is read in document order.

<Timeline.Root aria-label="Order tracking timeline"></Timeline.Root>

Keyboard Support#

Not applicable. Timeline is a presentational component — keyboard interaction depends on interactive content rendered inside events.