Project Information

Button / ButtonLink / IconButton / ButtonGroup

Button, ButtonLink, IconButton, ButtonGroup의 주요 props와 조합 패턴을 정리한 가이드 페이지입니다.

Button

Button / 디자인 props

Button은 size, color, variant, shape 같은 디자인 props를 조합해 다양한 액션 버튼을 구성합니다.

Prop

size

"large" | "medium" | "small"

default: "large"

Prop

color

"black" | "primary" | "secondary" | "point"

default: "black"

Prop

variant

"solid" | "line" | "text"

default: "solid"

solid와 line은 size, color, shape와 함께 사용할 수 있고, text는 color만 조합할 수 있습니다. text variant에서는 size와 shape를 받지 않습니다.

Prop

shape

"round" | "square"

default: "square"

shape는 solid 또는 line variant에서만 사용합니다. text variant에서는 적용되지 않습니다.

Prop

icon

React.ReactNode

Prop Spreading

Button 컴포넌트의 props 위임

Button의 디자인 props를 공유하면서 button 태그의 props를 그대로 전달합니다.

Prop

disabled

boolean

default: false

Prop

type

"button" | "submit" | "reset" | undefined

default: button

Prop

onClick

React.MouseEventHandler<HTMLButtonElement>

default: undefined

ButtonLink

ButtonLink / props 위임

ButtonLink는 Button과 동일한 디자인 props를 공유하고, 링크 이동에 필요한 Next Link props를 그대로 전달하는 컴포넌트입니다.

Prop

Button 디자인 props

icon | size | color | variant | shape

ButtonLink도 Button과 같은 icon, size, color, variant, shape props를 사용합니다. text variant는 color만 조합할 수 있고 size와 shape는 받지 않습니다.

홈으로 이동

주요 링크

보조 링크

Prop

href

string | UrlObject

ButtonLink에서 필수로 전달해야 하는 이동 경로입니다.

홈으로 이동

Prop

native link props

target | rel | prefetch | replace ...

정의하지 않은 링크 관련 props는 Next Link로 위임됩니다. 외부 링크에서는 target, rel 같은 속성을 함께 지정할 수 있습니다.

Next.js Docs 새창 열기

IconButton

IconButton / props 위임

IconButton은 Button의 디자인 props를 공유하면서 button 태그의 props를 그대로 전달합니다.

Prop

children

React.ReactNode

아이콘 노드를 children으로 전달합니다. icon prop과 variant="text"는 사용할 수 없습니다.

Prop

aria-label

string

default: undefined

텍스트 없이 아이콘만 보이는 버튼에서는 접근성 이름을 반드시 지정합니다.

ButtonGroup

ButtonGroup / ButtonGroup.Item

ButtonGroup은 버튼을 가로로 배치하고, ButtonGroup.Item 단위로 각 항목의 폭 패턴을 조정할 때 사용합니다.

Prop

children

React.ReactNode

버튼은 ButtonGroup.Item으로 감싸서 배치합니다. 기본 레이아웃에서는 각 item이 가능한 영역을 균등하게 나눠 가집니다.

Prop

ButtonGroup.Item / shouldAutoWidth

boolean

default: false

ButtonGroup.Item의 shouldAutoWidth가 true이면 해당 item은 가능한 영역을 꽉 채우지 않고, 콘텐츠 너비에 맞춰 고정됩니다.

Props Table

Button props 한눈에 보기

Button 컴포넌트에서 자주 사용하는 핵심 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	버튼 내부에 렌더링할 라벨 또는 커스텀 콘텐츠입니다.
`color`	`"black" \| "primary" \| "secondary" \| "point"`	`"black"`	Optional	버튼의 컬러 톤을 지정합니다.
`variant`	`"solid" \| "line" \| "text"`	`"solid"`	Optional	버튼의 표현 방식을 정합니다. `text` variant에서는 `size`와 `shape`를 함께 사용하지 않습니다.
`size`	`"large" \| "medium" \| "small"`	`"large"`	Optional	버튼의 높이와 패딩을 조절합니다. `solid` 또는 `line` variant에서 사용합니다.
`shape`	`"round" \| "square"`	`"square"`	Optional	버튼 외곽 모양을 제어합니다. `text` variant에서는 적용되지 않습니다.
`icon`	`React.ReactNode`	`undefined`	Optional	라벨 앞에 아이콘을 함께 렌더링합니다.
`className`	`string`	`undefined`	Optional	추가 스타일링이 필요할 때 커스텀 클래스를 전달합니다.
`disabled`	`boolean`	`false`	Optional	네이티브 button 속성으로, 비활성 상태를 적용합니다.
`type`	`"button" \| "submit" \| "reset"`	`"button"`	Optional	폼 내부에서 버튼의 동작 방식을 지정합니다.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	`undefined`	Optional	클릭 이벤트 핸들러를 전달합니다.

ButtonProps는 React.ButtonHTMLAttributes<HTMLButtonElement>를 확장하므로 name, value, aria-* 같은 네이티브 button props도 함께 전달할 수 있습니다.

Props Table

ButtonLink props 한눈에 보기

ButtonLink에서 자주 사용하는 디자인 props와 Link 위임 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	링크 버튼 내부에 렌더링할 텍스트 또는 커스텀 콘텐츠입니다.
`href`	`string \| UrlObject`	-	Required	이동할 경로입니다. Next Link의 필수 prop입니다.
`color`	`"black" \| "primary" \| "secondary" \| "point"`	`"black"`	Optional	버튼 링크의 컬러 톤을 지정합니다.
`variant`	`"solid" \| "line" \| "text"`	`"solid"`	Optional	링크의 표현 방식을 정합니다. `text` variant에서는 `size`와 `shape`를 함께 사용하지 않습니다.
`size`	`"large" \| "medium" \| "small"`	`"large"`	Optional	링크의 높이와 패딩을 조절합니다. `solid` 또는 `line` variant에서 사용합니다.
`shape`	`"round" \| "square"`	`"square"`	Optional	링크 외곽 모양을 제어합니다. `text` variant에서는 적용되지 않습니다.
`icon`	`React.ReactNode`	`undefined`	Optional	링크 라벨 앞에 아이콘을 함께 렌더링합니다.
`className`	`string`	`undefined`	Optional	추가 스타일링이 필요할 때 커스텀 클래스를 전달합니다.
`target`	`string`	`undefined`	Optional	새 창 열기 같은 링크 동작이 필요할 때 지정합니다.
`rel`	`string`	`undefined`	Optional	외부 링크에서 보안 속성을 함께 지정할 때 사용합니다.
`prefetch`	`boolean`	`Next Link default`	Optional	내부 링크 프리페치 동작을 제어합니다.
`replace / scroll`	`boolean`	`Next Link default`	Optional	히스토리 교체 여부와 이동 후 스크롤 동작을 제어합니다.

ButtonLinkProps는 ButtonBaseProps, ButtonDesignProps와 Next Link props를 조합합니다. 표에 없는 onClick, locale, shallow 같은 Link 관련 props도 함께 전달할 수 있습니다.

Props Table

IconButton props 한눈에 보기

IconButton에서 자주 사용하는 핵심 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	버튼 안에 렌더링할 아이콘 노드입니다.
`aria-label`	`string`	`undefined`	Optional	아이콘만 표시되므로 실사용에서는 접근성 이름을 지정하는 것을 권장합니다.
`color`	`"black" \| "primary" \| "secondary" \| "point"`	`"black"`	Optional	아이콘 버튼의 컬러 톤을 지정합니다.
`variant`	`"solid" \| "line"`	`"solid"`	Optional	IconButton은 variant="text"를 지원하지 않고 solid 또는 line만 사용합니다.
`size`	`"large" \| "medium" \| "small"`	`"large"`	Optional	버튼의 크기를 조절합니다.
`shape`	`"round" \| "square"`	`"square"`	Optional	버튼 외곽 모양을 제어합니다.
`className`	`string`	`undefined`	Optional	추가 스타일링이 필요할 때 커스텀 클래스를 전달합니다.
`disabled`	`boolean`	`false`	Optional	네이티브 button 속성으로, 비활성 상태를 적용합니다.
`type`	`"button" \| "submit" \| "reset"`	`"button"`	Optional	폼 내부에서 버튼의 동작 방식을 지정합니다.
`onClick`	`React.MouseEventHandler<HTMLButtonElement>`	`undefined`	Optional	클릭 이벤트 핸들러를 전달합니다.

IconButtonProps는 ButtonProps에서 icon을 제거하고 variant를 "solid" | "line"으로 제한한 타입입니다. 아이콘은 icon prop이 아니라 children으로 전달합니다.

Props Table

ButtonGroup / ButtonGroup.Item props 한눈에 보기

ButtonGroup과 ButtonGroup.Item의 레이아웃 관련 props를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	보통 ButtonGroup.Item들을 자식으로 전달해 가로 배치를 구성합니다.
`className`	`string`	`undefined`	Optional	그룹 루트에 커스텀 클래스를 추가합니다.

ButtonGroup은 내부에서 buttonGroup__wrap 레이아웃을 만들고, 각 자식은 보통 ButtonGroup.Item으로 감싸서 사용합니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	각 그룹 셀 안에 배치할 버튼 또는 커스텀 콘텐츠입니다.
`className`	`string`	`undefined`	Optional	개별 item 래퍼에 커스텀 클래스를 추가합니다.
`shouldAutoWidth`	`boolean`	`false`	Optional	true이면 해당 item이 남는 공간을 균등 분배하지 않고 콘텐츠 너비에 맞춰집니다.

ButtonGroup.Item은 별도 export가 아니라 ButtonGroup.Item 정적 프로퍼티로 제공됩니다.