liminfo

HTMX Reference

HTMX 속성, 이벤트, 확장 기능 빠른 참조 가이드

20개 결과

HTMX Reference 소개

HTMX 레퍼런스는 모든 HTMX HTML 속성을 검색할 수 있는 빠른 참조 도구입니다. HTMX는 JavaScript를 작성하지 않고 HTML 속성만으로 AJAX, CSS 트랜지션, WebSocket, Server-Sent Events를 추가할 수 있는 경량 JavaScript 라이브러리입니다. 이 레퍼런스는 요청, 트리거, 타겟/스왑, 기타의 네 가지 카테고리로 정리되어 있어 개발자가 필요한 속성과 구문을 즉시 찾을 수 있습니다.

Django, Rails, Laravel, FastAPI, Node.js 같은 서버 렌더링 HTML 프레임워크와 함께 작업하는 프론트엔드 개발자와 풀스택 엔지니어들은 검색 입력 디바운싱을 위한 hx-trigger의 delay와 changed 수정자, 무한 스크롤 리스트 추가를 위한 hx-swap="beforeend", SPA 스타일 내비게이션을 위한 hx-push-url, 기존 링크와 폼을 AJAX로 점진적 향상시키는 hx-boost 패턴을 이 레퍼런스로 빠르게 확인합니다.

레퍼런스는 모든 요청 메서드(hx-get, hx-post, hx-put, hx-delete, hx-patch), 여덟 가지 스왑 모드(innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none), "every Ns" 구문을 사용한 폴링 트리거, hx-indicator, hx-confirm, hx-vals, hx-headers, hx-ext, hx-on 같은 유틸리티 속성을 다룹니다. 모든 항목에는 실제로 동작하는 HTML 예제가 포함되어 있습니다.

주요 기능

  • 5가지 HTTP 메서드 속성 전체 커버: hx-get, hx-post, hx-put, hx-delete, hx-patch와 실제 HTML 예제
  • hx-trigger 수정자: once, changed, delay:500ms, throttle, from, keyup, intersect, every Ns 폴링
  • hx-swap 모드: innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none과 스왑 타이밍
  • CSS 선택자와 상대 참조(closest, find, next, previous)를 사용하는 hx-target
  • 부분 업데이트를 위한 서버 응답에서 특정 요소를 추출하는 hx-select
  • 일반 앵커와 폼 요소를 점진적으로 AJAX 요청으로 변환하는 hx-boost
  • 요청 커스터마이즈: 추가 파라미터를 위한 hx-vals, 커스텀 헤더를 위한 hx-headers, 확인 다이얼로그를 위한 hx-confirm
  • 브라우저 히스토리 통합을 위한 hx-push-url, 로딩 스피너를 위한 hx-indicator, 확장 기능을 위한 hx-ext

자주 묻는 질문

HTMX란 무엇이고 React나 Vue와 어떻게 다른가요?

HTMX는 JavaScript를 작성하지 않고 특수 hx-* 속성만으로 AJAX 요청을 발행하고 서버 응답으로 DOM 일부를 교체합니다. React와 Vue는 클라이언트에서 상태와 렌더링을 관리하는 컴포넌트 기반 JavaScript 프레임워크입니다. HTMX는 상태를 서버에 유지하고 HTML 조각을 반환하므로 전체 SPA 아키텍처 없이 인터랙티비티를 원하는 서버 렌더링 앱에 이상적입니다.

hx-trigger는 어떻게 작동하고 어떤 수정자를 사용할 수 있나요?

hx-trigger는 요청을 시작하는 DOM 이벤트를 지정합니다. 기본값은 요소의 자연스러운 이벤트입니다(버튼은 click, 입력은 change). 수정자로 동작을 세밀하게 조정합니다: changed는 값이 변경될 때만 발동, delay:500ms는 요청을 디바운스, once는 첫 번째에만 발동, throttle:1s는 반복 트리거를 속도 제한, every 2s는 폴링 간격을 만듭니다. 여러 트리거는 쉼표로 구분하여 나열할 수 있습니다.

hx-swap의 모든 값과 의미는 무엇인가요?

innerHTML(기본값)은 대상의 내부 콘텐츠를 교체합니다. outerHTML은 대상 요소 자체를 교체합니다. beforebegin은 대상 앞에, afterbegin은 첫 번째 자식으로, beforeend는 마지막 자식으로, afterend는 대상 뒤에 삽입합니다. delete는 대상을 완전히 제거하고, none은 DOM을 업데이트하지 않고 응답을 버립니다(부수 효과만 있는 요청에 유용). swap:1s를 추가하면 CSS 트랜지션 지연으로 스왑을 애니메이션할 수 있습니다.

HTMX로 디바운스된 검색을 구현하는 방법은?

검색 입력에 hx-get="/search", hx-trigger="keyup changed delay:500ms", hx-target="#results"를 추가합니다. changed 수정자는 값이 실제로 변경될 때만 요청을 발동하고(화살표 키 제외), delay:500ms는 마지막 키 입력 후 500ms를 기다린 후 전송합니다. 이것이 클래식한 디바운스 패턴입니다. 서버는 HTML 조각을 반환하고 HTMX가 이를 #results에 삽입합니다.

hx-boost는 무슨 역할을 하나요?

부모 요소(예: nav)에 hx-boost="true"를 추가하면 모든 자식 앵커 링크와 폼 제출이 AJAX 요청으로 변환됩니다. 응답 body로 페이지 body가 교체되고 브라우저 URL이 pushState로 업데이트됩니다. href나 action 속성을 변경하지 않고 일반 HTML 링크에서 SPA 스타일 내비게이션을 만들 수 있습니다. JavaScript가 비활성화되면 일반 방식으로 우아하게 동작합니다.

HTMX 요청에 추가 데이터나 커스텀 헤더를 보내는 방법은?

hx-vals로 추가 키-값 쌍을 JSON으로 포함합니다: hx-vals='{"csrf": "token123"}'. HTTP 헤더는 hx-headers를 사용합니다: hx-headers='{"X-Custom-Header": "value"}'. 두 속성 모두 속성에 JSON 문자열을 직접 사용하거나 js: 접두사를 붙인 JavaScript 표현식을 사용합니다. hx-vals 값은 폼 데이터에 병합되거나 GET 요청의 쿼리 파라미터로 포함됩니다.

hx-push-url은 브라우저 뒤로/앞으로 탐색을 어떻게 활성화하나요?

hx-push-url="true"는 성공적인 응답 후 History API의 pushState를 사용해 요청 URL을 브라우저 히스토리 스택에 추가합니다. 사용자는 일반 페이지 로드처럼 뒤로/앞으로 탐색할 수 있습니다. hx-push-url="/page/2"처럼 특정 경로를 지정하면 실제 요청 URL 대신 해당 경로가 추가됩니다. hx-boost와 함께 사용하면 완전한 SPA 스타일 내비게이션을 구현할 수 있습니다.

HTMX로 로딩 스피너를 표시하는 방법은?

요청하는 요소에 hx-indicator="#spinner"를 추가하고 #spinner 요소에 display:none을 설정합니다. HTMX는 요청이 진행 중일 때 인디케이터 요소에 htmx-request CSS 클래스를 자동으로 추가하고 완료되면 제거합니다. CSS에서 .htmx-request { display: block; }으로 스타일을 지정합니다. 트리거 요소 자체에 htmx-request 클래스를 사용해 인라인 로딩 상태를 표시할 수도 있습니다.