useHighlight

검색 결과 같은 텍스트 일치 항목을 브라우저의 CSS Custom Highlight API로 표시합니다. 훅은 일치 항목마다 Range를 찾아 CSS.highlights의 Highlight에 더하고, CSS는 ::highlight(name)으로 그 범위를 칠합니다. <mark> 요소를 추가하지 않으므로 DOM, 선택 영역, 포커스는 그대로입니다.

검색할 요소에 ref를 두고 query를 넘기세요. ref 아래의 텍스트나 요소가 바뀌면 훅이 다시 검색합니다. caseSensitive를 설정하지 않으면 대소문자를 구분하지 않으며, 쿼리는 패턴이 아니라 일반 텍스트입니다. 목록을 넘기면 그중 어느 단어든 일치시킵니다.

const found = useHighlight({ name: 'search', query })

<article ref={found.ref}>{children}</article>
<output>{found.matches.length} results</output>

::highlight(search) {
	background-color: var(--todae-color-status-warning-bg);
	color: var(--todae-color-fg-default);
}

matches에는 일치 항목마다 살아 있는(live) Range가 문서 순서대로 들어 있습니다. CSS로 숨긴 텍스트도 일치 항목에 들어갑니다. 일치 항목은 텍스트 노드 하나 안에 있어야 하므로, fo<b>o</b>처럼 마크업으로 나뉜 단어는 찾지 못합니다.

현재 결과를 표시하려면, 그 범위를 다른 이름의 두 번째 훅에 ranges로 넘기고 priority를 더 높게 주어 위에 칠해지게 하세요. 위 데모가 이렇게 합니다. 훅마다 다른 name을 주세요. 여러 이름을 같은 스타일로 칠하려면 ::highlight(a), ::highlight(b)처럼 나열하세요. type은 맞춤법과 문법 표시를 위해 spelling-error나 grammar-error를 설정합니다.

훅은 아무것도 알리지 않습니다. 스크린 리더 사용자에게 개수가 필요하면 <output>이나 다른 라이브 영역에 보여 주세요.

언제 쓰나요

언제: DOM을 바꾸지 않고 텍스트를 표시할 때. 페이지 내 찾기, 목록이나 문서의 검색 결과, 필터에서 일치한 글자.

쓰지 않을 때: 접근성 트리에 있어야 하는 강조 → 실제 <mark> 요소. 목록에서 선택된 항목 하나 → OptionList처럼 aria-selected와 스타일.

Props