아이콘
Material Symbols 폰트 기반의 아이콘 컴포넌트입니다. 두 가지 방법으로 아이콘을 사용할 수 있습니다.
폰트 의존성
@newtil/materials/index.css 는 Google Fonts 에서 Material Symbols 폰트(Outlined·Rounded·Sharp) 를 @import 합니다. 아이콘은 이 폰트의 글리프이므로 런타임에 fonts.googleapis.com / fonts.gstatic.com 접근이 필요합니다. 패키지 자체에는 폰트 파일이 포함되어 있지 않습니다.
- 오프라인 환경이나 CSP(
style-src,font-src)로 Google Fonts 가 막힌 환경에서는 아이콘 자리에 아이콘 이름 텍스트(예:home)가 그대로 보입니다. - 번들러(Next.js Turbopack · Vite)로
index.css를 import 하면 외부@import가 버려집니다. 앱의<head>에 Google Fonts<link>를 직접 추가하세요(시작하기 참고). - 이런 환경에서는 Material Symbols 폰트를 직접 호스팅하고
@font-face로 같은 패밀리 이름("Material Symbols Outlined"등)을 선언하면 됩니다.--icon-family변수로 패밀리 이름을 바꿀 수도 있습니다. - 아이콘을 쓰지 않는 페이지도
index.css를 가져오는 순간 폰트 요청이 발생합니다.
방법 1. icon:이름 클래스 (Essential 아이콘)
미리 정의된 60개 핵심 아이콘을 클래스 이름으로 사용합니다.
소스 코드 보기
방법 2. data-icon 속성 (전체 아이콘)
Essential에 없는 아이콘은 data-icon 속성으로 사용합니다. Material Symbols 폰트의 ligature 기능을 이용하므로, 별도의 CSS 정의 없이 아이콘 이름만으로 렌더링됩니다.
소스 코드 보기
전체 아이콘 목록은 Google Material Symbols에서 검색할 수 있습니다. 아이콘 이름은 소문자 + 언더스코어 형식입니다 (예: shopping_cart, arrow_forward, dark_mode).
방법 3. 아이콘 추가하기 (icon:이름 클래스 직접 정의)
Essential 60개에 없는 아이콘을 프로젝트에서 자주 쓴다면 icon:이름 클래스를 직접 정의합니다. 패키지는 틀(.m3-icon 이 ::before 를 Material Symbols 글리프로 그리는 규칙)만 제공하고, 어떤 아이콘을 클래스로 둘지는 사용자가 정합니다.
정의는 한 줄입니다. content 에 Material Symbols 아이콘 이름을 그대로 쓰면 폰트의 ligature 가 글리프로 바꿉니다.
/* 프로젝트 CSS — @newtil/materials 를 import 한 뒤 어디든 */
.icon\:rocket::before { content: "rocket_launch"; }
.icon\:cart::before { content: "shopping_cart"; }
.icon\:account::before { content: "account_circle"; }<i class="m3-icon icon:rocket"></i>
<i class="m3-icon icon:cart icon-color:primary"></i>
<i class="m3-icon icon:account icon-size:lg icon-filled:1"></i>소스 코드 보기
- 클래스 이름은 자유입니다. 아이콘 이름과 같을 필요가 없어서
icon:cart처럼 짧게 둘 수 있습니다. - 크기·색·채움 옵션(
icon-size:,icon-color:,icon-filled:)은 Essential 아이콘과 똑같이 붙습니다. - Essential 은
content: "\e88a"처럼 코드포인트를 쓰지만 이름(ligature)으로 써도 결과는 같습니다. 코드포인트는 Google Material Symbols 에서 아이콘을 고르면 "Code point" 로 표시됩니다. .m3-icon은 폰트 글리프 전용입니다. Material Symbols 에 없는 SVG 아이콘은<svg>를 직접 넣으세요.
Essential 60개 아이콘 목록
Navigation
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:home | 홈 | |
icon:menu | 메뉴 | |
icon:close | 닫기 | |
icon:arrow_back | 뒤로 | |
icon:arrow_forward | 앞으로 | |
icon:expand_more | 펼치기 | |
icon:expand_less | 접기 | |
icon:chevron_left | 왼쪽 | |
icon:chevron_right | 오른쪽 | |
icon:more_vert | 더보기 (세로) | |
icon:more_horiz | 더보기 (가로) | |
icon:refresh | 새로고침 | |
icon:settings | 설정 | |
icon:apps | 앱 | |
icon:launch | 실행 |
Actions
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:add | 추가 | |
icon:remove | 제거 | |
icon:edit | 편집 | |
icon:delete | 삭제 | |
icon:save | 저장 | |
icon:check | 체크 | |
icon:clear | 지우기 | |
icon:cancel | 취소 | |
icon:done | 완료 | |
icon:search | 검색 | |
icon:share | 공유 | |
icon:download | 다운로드 | |
icon:upload | 업로드 | |
icon:copy | 복사 | |
icon:visibility | 보이기 | |
icon:visibility_off | 숨기기 | |
icon:lock | 잠금 | |
icon:lock_open | 잠금 해제 | |
icon:sync | 동기화 | |
icon:info | 정보 |
Communication
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:email | 이메일 | |
icon:phone | 전화 | |
icon:chat | 채팅 | |
icon:notifications | 알림 | |
icon:send | 보내기 | |
icon:reply | 답장 | |
icon:help | 도움말 | |
icon:feedback | 피드백 |
Media
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:play_arrow | 재생 | |
icon:pause | 일시정지 | |
icon:stop | 정지 | |
icon:volume_up | 볼륨 높임 | |
icon:volume_off | 음소거 | |
icon:mic | 마이크 | |
icon:mic_off | 마이크 꺼짐 |
Files
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:folder | 폴더 | |
icon:folder_open | 폴더 열기 | |
icon:attach_file | 파일 첨부 | |
icon:cloud | 클라우드 | |
icon:description | 문서 |
Social
| 모양 | 클래스 | 아이콘 이름 |
|---|---|---|
icon:person | 사용자 | |
icon:people | 그룹 | |
icon:favorite | 좋아요 | |
icon:star | 별 | |
icon:thumb_up | 추천 |
크기 옵션
icon-size: 클래스로 아이콘 크기를 변경합니다.
소스 코드 보기
숫자 별칭도 사용 가능합니다: icon-size:1 ~ icon-size:5
| 클래스 | 별칭 | 크기 | Optical Size |
|---|---|---|---|
icon-size:xs | icon-size:1 | 1rem (16dp) | 20 |
icon-size:sm | icon-size:2 | 1.25rem (20dp) | 20 |
icon-size:md | icon-size:3 | 1.5rem (24dp) | 24 |
icon-size:lg | icon-size:4 | 2.5rem (40dp) | 40 |
icon-size:xl | icon-size:5 | 3rem (48dp) | 48 |
색상 옵션
icon-color: 클래스로 아이콘 색상을 지정합니다.
소스 코드 보기
| 클래스 | 설명 | |:---😐---|---| | icon-color:primary | 주요 색상 | | icon-color:primary-hover | 주요 색상 (hover) | | icon-color:primary-active | 주요 색상 (active) | | icon-color:secondary | 보조 색상 | | icon-color:secondary-hover | 보조 색상 (hover) | | icon-color:tertiary | 3차 색상 | | icon-color:tertiary-hover | 3차 색상 (hover) | | icon-color:surface | 표면 색상 | | icon-color:on-surface | icon-color:text 와 동일 (--color-text) | | icon-color:text | 텍스트 색상 | | icon-color:text-muted | 흐린 텍스트 | | icon-color:text-subtle | 미묘한 텍스트 | | icon-color:success | 성공 | | icon-color:warning | 경고 | | icon-color:danger | 위험 | | icon-color:white | 흰색 (#ffffff) | | icon-color:black | 검정 (#000000) |
Filled (채움) 옵션
icon-filled:1 클래스로 아이콘을 채움 스타일로 전환합니다.
소스 코드 보기
아이콘 스타일
Material Symbols는 3가지 스타일을 지원합니다.
소스 코드 보기
세밀한 조정
| 클래스 | 값 | 설명 |
|---|---|---|
icon-weight:100 ~ icon-weight:700 | 100~700 | 굵기 조정 |
icon-grade:low | -25 | 가는 그레이드 |
icon-grade:normal | 0 | 기본 그레이드 |
icon-grade:high | 200 | 굵은 그레이드 |
icon-optical:20 ~ icon-optical:48 | 20, 24, 40, 48 | 광학 크기 |
m3-deco와의 조합
m3-deco 컴포넌트에서도 아이콘 클래스와 data-icon 속성을 동일하게 사용할 수 있습니다.
소스 코드 보기
버튼 안에서 아이콘 사용
소스 코드 보기
Variable API
| 변수 | 기본값 | 설명 |
|---|---|---|
--icon-size | 1.5rem | 아이콘 크기 (24dp) |
--icon-family | "Material Symbols Outlined" | 폰트 패밀리 |
--icon-fill | 0 | 채움 (0=outlined, 1=filled) |
--icon-weight | 400 | 굵기 (100~700) |
--icon-grade | 0 | 그레이드 (-25, 0, 200) |
--icon-optical-size | 24 | 광학 크기 (20, 24, 40, 48) |
--icon-hover-border-radius | 50% | 호버 효과 모서리 |
--icon-hover-scale | 1.3 | 호버 시 확대 비율 |
--icon-hover-inner-scale | 0.8 | 호버 시 내부 축소 비율 |