useClipboard

useClipboard(options?)는 text를 클립보드에 쓰는 copy(text), 가장 최근 복사의 결과인 status, 그 결과가 가리키는 텍스트인 text, 그리고 reset()을 반환합니다. 코드 블록, 링크, 메시지의 복사 버튼처럼 복사 버튼에 쓰세요.

const { copy, status } = useClipboard();

<Button.Root onClick={() => copy(command)}>Copy command</Button.Root>
{status === 'copied' ? <Text.Root>Copied</Text.Root> : null}

copy는 navigator.clipboard.writeText를 호출하고, 텍스트가 복사되면 true로, 복사되지 않으면 false로 resolve됩니다. 가장 최근 복사가 끝나면 status는 'copied' 또는 'failed'가 되고, text는 그 복사에 넘긴 텍스트가 됩니다. 둘 다 resetAfter가 지나거나 reset()을 호출하면 'idle'과 null로 돌아갑니다. resetAfter의 기본값은 2000밀리초이고, resetAfter: false를 전달하면 다음 복사나 reset()까지 유지합니다. 복사가 진행 중인 동안에는 이전 결과가 그대로 남습니다. 복사가 겹치면 가장 최근 복사만 status를 정하고 알려집니다.

execCommand 대체 경로는 없습니다. 보안 컨텍스트가 아닌 페이지처럼 Clipboard API가 없거나 거부되는 곳에서는 복사가 실패합니다.

접근성을 지키는 조합

Todae가 맡는 것: useAnnouncer로 가장 최근 복사의 결과를 알립니다. 복사 뒤에는 copied 문자열을 polite로, 복사가 실패하면 copyFailed 문자열을 assertive로 읽습니다. copiedMessage나 failedMessage를 전달하지 않으면 둘 다 StringsProvider에서 옵니다. 컴포넌트가 언마운트된 뒤에 끝난 복사도 알립니다.

직접 제공할 것: 무엇을 복사하는지 말하는 이름이 있는 버튼. 페이지에 복사 버튼이 여럿이면 "Copy" 대신 "Copy command"처럼 쓰세요. 화면을 보는 사용자를 위해 status로 그 옆에 보이는 결과. StringsProvider나 옵션으로 넘기는, 읽는 사람의 언어로 된 메시지.

주의할 점: Alert처럼 자체 라이브 영역 안에 있는 보이는 결과는 두 번 읽힙니다. 아무것도 읽지 않으려면 빈 copiedMessage나 failedMessage를 전달하세요. 버튼 자체의 텍스트를 "Copied"로 바꾸면 스크린 리더가 알림과 함께 그 텍스트도 읽을 수 있습니다.

언제 쓰나요

언제: 명령어, 링크, 메시지처럼 제품이 이미 가진 텍스트를 복사하는 컨트롤.

쓰지 않을 때: 이미지나 HTML 같은 서식 있는 콘텐츠 복사 → 직접 작성한 코드의 navigator.clipboard.write. 읽는 사람이 직접 선택해 복사하는 텍스트 → 브라우저가 이미 처리합니다.

Props