# useTimelineContext

This hooks can be used to access the timeline's state, and also provides a set of useful helper functions.

### API

#### `style`

```typescript
style: CSSProperties
```

A set of mendatory style properties, that must be applied to the timeline container element.

#### `timelineRef`

```typescript
timelineRef: React.MutableRefObject<HTMLElement | null>
```

The timeline container element's ref.

#### `setTimelineRef`

```typescript
setTimelineRef: (element: HTMLElement | null) => void
```

A ref setter that must be passed to the timeline's container element.

#### `valueToPixels`

```typescript
valueToPixels: (value: number) => number
```

A helper function that receives a value, and returns the pixel representation in relation to the timeline's container element.

> 🧠 It can be used to infer elements' size and position in pixels, based on their duration. It is internally used in order to position items on the timeline.

#### `pixelsToValue`

```typescript
pixelsToValue: (pixels: number) => number
```

A helper function that receives pixels, and returns the equivalent duration for it, in relation to the timeline's container element.

> 🧠 It can be used to convert size and position to a value. It is internally used to infer items' update spans according to their updated position/width, in relation to the timeline's container element.

#### `getValueFromScreenX`

```typescript
getValueFromScreenX: (screenX: number) => number
```

A helper function that receives x position in the client's screen, and returns a date representation of that position, in relation to the timeline's container element.

> 🧠 It can be used to infer a time value from a mouse event. For example, you can use it to extract a date from a click event on the timeline.

#### `getDeltaXFromScreenX`

```typescript
getDeltaXFromScreenX: (screenX: number) => number
```

A helper function that receives x position in the client's screen, and returns the delta X distance from the timeline's start.

> 🧠 It can be used to infer a relative position for a custom item from a mouse event. For example, you can use it to place a custom item on the timeline from a pointer event.

#### `getSpanFromDragEvent`

```typescript
getSpanFromDragEvent: (event: DragEvent) => Span | null
```

A function that extracts span from a drag event. The drag event type can be one of the following:

{% code overflow="wrap" %}

```tsx
type DragEvent = DragStartEvent | DragEndEvent | DragCancelEvent | DragMoveEvent
```

{% endcode %}

This function is injected into all of dnd-kit's events, and allowes you to infer the dragged item's span from the event object. For example:

<pre class="language-tsx"><code class="lang-tsx">const onDragEnd = (event: DragEndEvent) => {
  const updatedSpan =
<strong>    event.active.data.current.getSpanFromDragEvent?.(event)
</strong>    
  // update your state using the updated span.
}
</code></pre>

By default, this helper uses the default drag span strategy. This can be overridden with `getSpanFromDragEventStrategy`

#### `getSpanFromResizeEvent`

```typescript
getSpanFromResizeEvent: (event: ResizeEvent) => Span | null
```

A function that extracts span from a drag event. The drag event type can be one of the following:

{% code overflow="wrap" %}

```tsx
type ResizeEvent = ResizeStartEvent | ResizeMoveEvent | ResizeEndEvent
```

{% endcode %}

This function is injected into all of dnd-timeline's resize events, and allowes you to infer the dragged item's span from the event object. For example:

<pre class="language-tsx"><code class="lang-tsx">const onResizeEnd = (event: ResizeEndEvent) => {
  const updatedSpan =
<strong>    event.active.data.current.getSpanFromResizeEvent?.(event)
</strong>    
  // update your state using the updated span.
}
</code></pre>

By default, this helper uses the default resize span strategy. This can be overridden with `getSpanFromResizeEventStrategy`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.