# useItem

A hook to declare a timeline item.

Use this hook to declare an HTML element as an item in the timeline.

{% hint style="info" %}
This hook is based on dnd-kit's [useDraggable](https://docs.dndkit.com/api-documentation/draggable/usedraggable) hook.

Please make sure you fully understand it's concepts before trying to use it here.
{% endhint %}

### Options

#### `id`

```tsx
id: string
```

A unique id to identify this item.

#### `span`

```tsx
span: Span
```

An object representing the start and end values of the item.

#### `disabled?`

```tsx
disabled?: boolean
```

An optional boolean to disable the interactivity of the item.

#### `data?`

```tsx
data?: object
```

Custom data that can be passed to the row.

> 🧠 This can be passed to rows to identify their type. This type can later be used in the event callbacks to apply different behaviors to different row types.

{% code title="Item.tsx" %}

```tsx
useItem({
  id: props.id,
  span: props.span,
  data: { type: 'timeline-item' },
})
```

{% endcode %}

{% code title="Timeline.tsx" %}

```tsx
const onDragEnd = (event: DragEndEvent) => {
  const updatedSpan =
    event.active.data.current.getSpanFromDragEvent?.(event)

  const rowType = event.active.data.current.type
  
  if (rowType === 'timeline-row' && itemType === 'timeline-item') {
    // update
  }
    
  if (rowType === 'timeline-disabled-row' && itemType === 'timeline-item') {
    // don't update, and pop an error message
  }
}
```

{% endcode %}

#### `resizeHandleWidth?`

```tsx
resizeHandleWidth?: number
```

An optional resize handler width, in pixels.

defaults to the [`resizeHandleWidth`](/dnd-timeline/documentation/timelinecontext.md#resizehandlewidth) provided to the context. 

Choosing a larger or a smaller `handleWidth` will change the resize action's sensitivity.

{% hint style="info" %}
**If set to `0`, resizing will be disabled for the item.**
{% endhint %}

### Events

useItem can also receive callbacks, that will be called when the relevant event is triggered.

For example:

```tsx
const onResizeMove = useCallback(() => {
  const updatedSpan =
    event.active.data.current.getSpanFromResizeEvent?.(event)

  // update some local state with the updated-span
}, [])

useItem({
  id: props.id,
  span: props.span,
  onResizeMove,
})
```

#### onResizeStart?

```tsx
onResizeMove?: (event: ResizeStartEvent) => void
```

```tsx
type ResizeStartEvent = {
  active: Omit<Active, 'rect'>
  direction: DragDirection // 'start' | 'end'
}
```

#### onResizeMove?

```tsx
onResizeMove?: (event: ResizeMoveEvent) => void
```

```tsx
type ResizeMoveEvent = {
  active: Omit<Active, 'rect'>
  delta: {
    x: number
  }
  direction: DragDirection // 'start' | 'end'
}
```

#### onResizeEnd?

```tsx
onResizeMove?: (event: ResizeEndEvent) => void
```

```tsx
type ResizeEndEvent = {
  active: Omit<Active, 'rect'>
  delta: {
    x: number
  }
  direction: DragDirection // 'start' | 'end'
}
```

### API

{% hint style="info" %}
All of dnd-kit [useDraggable](https://docs.dndkit.com/api-documentation/draggable/usedraggable#properties) api are returned as well.
{% endhint %}

#### `itemStyle`

```tsx
itemStyle: CSSProperties
```

Basic style properties that must be passed to the item wrapper element.

#### `itemContentStyle`

```tsx
itemContentStyle: CSSProperties
```

Basic style properties that must be passed to the item's children wrapper element.


---

# 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/item/useitem.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.