AG Grid Tooltip 사용법

tooltipField · tooltipValueGetter · headerTooltip · tooltipShowDelay · tooltipShowMode 한 번에 정리

AG Grid에서 툴팁은 별도 플러그인 없이 ColDef나 GridOptions만으로 구현할 수 있습니다.
이 글에서는 셀 툴팁·헤더 툴팁·표시 조건·타이밍 제어까지 자주 쓰는 패턴을 모두 정리합니다.

1. 툴팁 개요

AG Grid 툴팁은 셀, 헤더, 그룹 행 등 다양한 영역에 추가할 수 있습니다.

방법	용도
`tooltipField`	데이터 필드 값을 그대로 표시
`tooltipValueGetter`	함수로 조건부·복합 텍스트 생성
`headerTooltip`	컬럼 헤더에 툴팁 추가

참고: AG Grid 기본 툴팁은 브라우저 네이티브 title 속성을 사용합니다.
커스텀 스타일이 필요하다면 Custom Tooltip Component를 구현하세요.

2. tooltipField

행 데이터의 특정 필드 값을 툴팁 텍스트로 사용합니다.
가장 간단한 방법으로, 데이터 객체의 키 이름만 지정하면 됩니다.

const columnDefs = [
  {
    field: 'athleteName',
    headerName: '선수명',
    tooltipField: 'athleteName',      // 셀과 같은 필드를 툴팁으로
  },
  {
    field: 'country',
    headerName: '국가',
    tooltipField: 'countryFullName',  // 다른 필드를 툴팁으로
  }
];

팁: tooltipField에 현재 컬럼의 field와 다른 필드명을 지정해도 됩니다.
예를 들어 셀에는 약어 코드를 표시하고, 툴팁에는 전체 이름을 보여주는 패턴이 자주 쓰입니다.

3. tooltipValueGetter

함수로 동작하며, 조건부 로직이나 가공된 문자열을 툴팁에 표시할 때 사용합니다.
valueGetter와 동일한 params 객체를 받습니다.

기본 사용법

{
  field: 'gold',
  headerName: '금메달',
  tooltipValueGetter: (params) => {
    const { gold, silver, bronze } = params.data;
    return `금: ${gold} | 은: ${silver} | 동: ${bronze}`;
  }
}

조건부 툴팁 예시

{
  field: 'score',
  headerName: '점수',
  tooltipValueGetter: (params) => {
    if (params.value === null || params.value === undefined) return '데이터 없음';
    if (params.value >= 90) return '우수 성적';
    if (params.value >= 70) return '양호';
    return '개선 필요';
  }
}

params 주요 속성

속성	타입	설명
`params.value`	`any`	현재 셀의 렌더링된 값
`params.data`	`RowData`	현재 행의 전체 데이터 객체
`params.colDef`	`ColDef`	현재 컬럼의 ColDef 객체
`params.node`	`RowNode`	현재 행의 Row Node

4. headerTooltip

컬럼 헤더에 툴팁을 추가합니다.
컬럼명이 짧거나 약어일 때 전체 설명을 표시하는 용도로 자주 쓰입니다.

const columnDefs = [
  {
    field: 'ctr',
    headerName: 'CTR',
    headerTooltip: 'Click-Through Rate (클릭률)',
  },
  {
    field: 'roas',
    headerName: 'ROAS',
    headerTooltip: 'Return On Ad Spend (광고 수익률)',
  }
];

주의: headerTooltip은 함수가 아닌 문자열만 받습니다.
동적으로 헤더 툴팁을 생성해야 한다면 Custom Header Component를 사용하세요.

5. 딜레이 설정 3종

툴팁의 표시·숨김 타이밍을 GridOptions에서 밀리초(ms) 단위로 제어합니다.

tooltipShowDelay

마우스를 셀 위에 올린 뒤 툴팁이 나타나기까지 기다리는 시간입니다.
기본값은 2000ms이며, UX 개선을 위해 300~500ms로 줄이는 경우가 많습니다.

const gridOptions = {
  tooltipShowDelay: 500,   // 0.5초 후 표시
};

tooltipSwitchShowDelay

한 셀에서 다른 셀로 빠르게 이동할 때 새 툴팁이 나타나는 딜레이입니다.
이미 툴팁이 열려 있는 상태에서는 tooltipShowDelay 대신 이 값이 사용됩니다.
기본값 200ms.

const gridOptions = {
  tooltipShowDelay: 500,
  tooltipSwitchShowDelay: 100,  // 셀 이동 시 0.1초 후 전환
};

tooltipHideDelay

마우스가 셀을 벗어난 후 툴팁이 사라지기까지 기다리는 시간입니다.
기본값 10000ms(10초). 빠르게 닫히길 원하면 줄이세요.

const gridOptions = {
  tooltipHideDelay: 2000,  // 2초 후 사라짐
};

팁: tooltipShowDelay: 0으로 설정하면 마우스를 올리는 즉시 툴팁이 나타납니다.
의도치 않은 셀 이동 시에도 계속 뜰 수 있으니 tooltipSwitchShowDelay와 함께 조정하세요.

6. tooltipShowMode

툴팁을 언제 표시할지 결정하는 모드입니다.
GridOptions에서 설정하며, 두 가지 값 중 하나를 선택합니다.

값	동작	기본값
`'whenTruncated'`	셀 텍스트가 잘릴 때만 툴팁 표시	✅ 기본값
`'always'`	텍스트 잘림 여부와 관계없이 항상 표시	—

whenTruncated (기본값)

셀 너비보다 텍스트가 길어 잘린 경우에만 툴팁이 표시됩니다.

const gridOptions = {
  tooltipShowMode: 'whenTruncated',  // 기본값 — 생략해도 동일
  tooltipShowDelay: 500,
};

always

텍스트가 잘리지 않아도 툴팁을 항상 표시합니다.
tooltipValueGetter로 부가 정보를 넣었을 때 특히 유용합니다.

const gridOptions = {
  tooltipShowMode: 'always',
  tooltipShowDelay: 400,
};

모드별 동작 비교

상황	whenTruncated	always
텍스트가 셀 안에 모두 표시됨	툴팁 미표시	툴팁 표시
텍스트가 잘려 일부만 보임	툴팁 표시	툴팁 표시
tooltipValueGetter로 추가 정보 제공	잘린 경우만	항상

추천 조합: 셀 내용이 짧아도 추가 정보(전체 주소, 상세 설명 등)를 보여주고 싶다면
tooltipShowMode: 'always' + tooltipValueGetter를 함께 사용하세요.

7. 전체 예제 코드

JavaScript

const columnDefs = [
  {
    field: 'athlete',
    headerName: '선수',
    tooltipField: 'athlete',           // ① 셀 값 그대로 툴팁
    headerTooltip: '선수의 전체 이름', // ② 헤더 툴팁
  },
  {
    field: 'sport',
    headerName: '종목',
    headerTooltip: '참가 스포츠 종목',
    tooltipValueGetter: (p) =>         // ③ 동적 툴팁
      `${p.data.athlete} — ${p.data.sport} (${p.data.year})`,
  },
  {
    field: 'gold',
    headerName: '금',
    headerTooltip: '금메달 획득 수',
    tooltipValueGetter: (p) =>
      `금 ${p.data.gold} · 은 ${p.data.silver} · 동 ${p.data.bronze}`,
  },
];

const gridOptions = {
  columnDefs,
  rowData,
  tooltipShowMode: 'always',        // 항상 표시
  tooltipShowDelay: 400,            // 0.4초 후 표시
  tooltipSwitchShowDelay: 100,      // 셀 이동 시 0.1초 전환
  tooltipHideDelay: 3000,           // 3초 후 숨김
};

React (TSX)

import { AgGridReact } from 'ag-grid-react';
import type { ColDef } from 'ag-grid-community';

const colDefs: ColDef[] = [
  {
    field: 'name',
    tooltipField: 'name',
    headerTooltip: '직원 이름',
  },
  {
    field: 'dept',
    tooltipValueGetter: (p) => `부서: ${p.data.deptFull}`,
  },
];

export default function MyGrid() {
  return (
    <AgGridReact
      columnDefs={colDefs}
      rowData={rowData}
      tooltipShowMode="always"
      tooltipShowDelay={400}
      tooltipSwitchShowDelay={100}
      tooltipHideDelay={3000}
    />
  );
}

8. 속성 빠른 비교표

속성	위치	타입	기본값	설명
`tooltipField`	ColDef	`string`	—	행 데이터의 필드 값을 툴팁으로 사용
`tooltipValueGetter`	ColDef	`function`	—	함수로 동적 툴팁 문자열 반환
`headerTooltip`	ColDef	`string`	—	컬럼 헤더에 툴팁 텍스트 지정
`tooltipShowMode`	GridOptions	`string`	`'whenTruncated'`	`'whenTruncated'` \| `'always'`
`tooltipShowDelay`	GridOptions	`number`	`2000`	호버 후 표시까지 딜레이(ms)
`tooltipSwitchShowDelay`	GridOptions	`number`	`200`	툴팁 열린 상태에서 셀 이동 시 딜레이(ms)
`tooltipHideDelay`	GridOptions	`number`	`10000`	마우스 이탈 후 숨김까지 딜레이(ms)

핵심 요약

tooltipField — 데이터 필드 값을 그대로 툴팁에 표시. 가장 간단.
tooltipValueGetter — 함수로 조건부·복합 툴팁 텍스트 생성.
headerTooltip — 컬럼 헤더에 설명 추가. 문자열만 가능.
tooltipShowMode — 'whenTruncated'(기본) 또는 'always'. 잘린 경우만 or 항상 표시.
tooltipShowDelay — 기본 2000ms, 빠른 UX를 위해 300~500ms 권장.
tooltipSwitchShowDelay — 셀 간 이동 시 전환 딜레이. 기본 200ms.
tooltipHideDelay — 기본 10000ms, 사용자 경험에 맞게 줄여 사용.

블로그 검색

AG Grid Tooltip 사용법

AG Grid Tooltip 사용법

목차

1. 툴팁 개요

2. tooltipField

3. tooltipValueGetter

기본 사용법

조건부 툴팁 예시

params 주요 속성

4. headerTooltip

5. 딜레이 설정 3종

tooltipShowDelay

tooltipSwitchShowDelay

tooltipHideDelay

6. tooltipShowMode

whenTruncated (기본값)

always

모드별 동작 비교

7. 전체 예제 코드

JavaScript

React (TSX)

8. 속성 빠른 비교표

핵심 요약