useItem

A hook to declare a timeline item.

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

This hook is based on dnd-kit's useDraggable hook.

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

Options

id

id: string

A unique id to identify this item.

span

span: Span

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

disabled?

disabled?: boolean

An optional boolean to disable the interactivity of the item.

data?

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.

Item.tsx

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

Timeline.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
  }
}

resizeHandleWidth?

resizeHandleWidth?: number

An optional resize handler width, in pixels.

defaults to the resizeHandleWidth provided to the context.

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

If set to 0, resizing will be disabled for the item.

Events

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

For example:

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?

onResizeMove?: (event: ResizeStartEvent) => void

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

onResizeMove?

onResizeMove?: (event: ResizeMoveEvent) => void

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

onResizeEnd?

onResizeMove?: (event: ResizeEndEvent) => void

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

API

All of dnd-kit useDraggable api are returned as well.

itemStyle

itemStyle: CSSProperties

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

itemContentStyle

itemContentStyle: CSSProperties

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