Cell Tooltip

Cell tooltips let you attach contextual messages to individual cells or ranges. Use them to show input hints, validation feedback, or informational notes.

Note: Cell Tooltip is available in the Pro edition.

Setting a tooltip

Register a tooltip on a cell with setCellTooltip(). The tooltip is stored but not shown until you explicitly display it.

worksheet.setCellTooltip(
  { row: 1, col: 0 },
  { text: 'Enter the customer name', backgroundColor: '#1e40af', color: '#ffffff' }
)

TooltipRange

CellTooltipConfig

Showing and hiding

// Show the tooltip on a specific cell
worksheet.showCellTooltip({ row: 1, col: 0 })

// Hide the currently visible tooltip
worksheet.hideCellTooltip()

Only one tooltip is visible at a time. Calling showCellTooltip() automatically hides the previous one.

Updating a tooltip

Call setCellTooltip() again on the same cell to update its text or colors. If the tooltip is currently visible, it updates immediately.

// Initially show a hint
worksheet.setCellTooltip({ row: 1, col: 1 }, {
  text: 'Enter a valid email address',
  backgroundColor: '#1e40af',
})

// After validation fails, switch to an error
worksheet.setCellTooltip({ row: 1, col: 1 }, {
  text: 'Invalid email format',
  backgroundColor: '#b91c1c',
})

Removing a tooltip

// Remove a specific tooltip (hides it first if active)
worksheet.clearCellTooltip({ row: 1, col: 0 })

Practical example — form validation

A common pattern is using tooltips for input validation. Register hint tooltips on all required fields, then switch them to error tooltips after validation.

const FIELDS = [
  { row: 1, label: 'Name',  hint: 'Required — enter your full name' },
  { row: 2, label: 'Email', hint: 'Required — enter a valid email' },
  { row: 3, label: 'Phone', hint: 'Required — enter your phone number' },
]

// Step 1: Register hints for empty required fields (blue)
FIELDS.forEach(field => {
  worksheet.setCellTooltip({ row: field.row, col: 1 }, {
    text: field.hint,
    backgroundColor: '#1e40af',
    color: '#ffffff',
  })
})

// Show the first hint
worksheet.showCellTooltip({ row: FIELDS[0].row, col: 1 })

After the user fills in values and submits, validate and switch to error tooltips:

function validate() {
  const errors = []

  // Check empty fields
  FIELDS.forEach(field => {
    const value = worksheet.cell(field.row, 1).value
    if (!value || String(value).trim() === '') {
      errors.push({ row: field.row, message: `${field.label} is required` })
    }
  })

  // Check email format
  const email = worksheet.cell(2, 1).value
  if (email && !String(email).includes('@')) {
    errors.push({ row: 2, message: 'Invalid email format' })
  }

  // Update tooltips to show errors (red)
  errors.forEach(err => {
    worksheet.setCellTooltip({ row: err.row, col: 1 }, {
      text: err.message,
      backgroundColor: '#b91c1c',
      color: '#ffffff',
    })
  })

  // Show the first error
  if (errors.length > 0) {
    worksheet.showCellTooltip({ row: errors[0].row, col: 1 })
  }
}

Multi-cell tooltips

Tooltips can span multiple cells using rowSpan and colSpan:

worksheet.setCellTooltip(
  { row: 0, col: 0, rowSpan: 1, colSpan: 3 },
  { text: 'This section is read-only', backgroundColor: '#6b7280' }
)
worksheet.showCellTooltip({ row: 0, col: 0, rowSpan: 1, colSpan: 3 })