Basic Components

IconButton

A square icon-only button with customizable appearance, size, and shape. Supports loading state and renders as anchor when href is provided.

Source Edit this page

A square icon-only button with customizable appearance, size, and shape. Supports loading state and renders as an <a> when given an href. Always provide aria-label for accessibility.

Basic Usage

Drop an icon directly inside the IconButton. Each appearance prop maps to a semantic color from the active theme.

<Row flexWrap>
  <IconButton aria-label="Star"><Star /></IconButton>
  <IconButton secondary aria-label="Favorite"><Heart /></IconButton>
  <IconButton success aria-label="Confirm"><Check /></IconButton>
  <IconButton danger aria-label="Delete"><Trash2 /></IconButton>
  <IconButton warning aria-label="Notify"><Bell /></IconButton>
  <IconButton info aria-label="Info"><Info /></IconButton>
</Row>

Sizes

IconButton supports five sizes — xs, sm, md (default), lg, xl. Size drives the square aspect ratio, padding, and border-radius simultaneously via CSS variables.

<Row flexWrap itemsEnd>
  <Col itemsCenter>
    <IconButton xs aria-label="Star xs"><Star /></IconButton>
    <Text sm secondary>xs</Text>
  </Col>
  <Col itemsCenter>
    <IconButton sm aria-label="Star sm"><Star /></IconButton>
    <Text sm secondary>sm</Text>
  </Col>
  <Col itemsCenter>
    <IconButton aria-label="Star md"><Star /></IconButton>
    <Text sm secondary>md</Text>
  </Col>
  <Col itemsCenter>
    <IconButton lg aria-label="Star lg"><Star /></IconButton>
    <Text sm secondary>lg</Text>
  </Col>
  <Col itemsCenter>
    <IconButton xl aria-label="Star xl"><Star /></IconButton>
    <Text sm secondary>xl</Text>
  </Col>
</Row>

Variants

IconButton renders as outline (default) or filled.

<Col>
  <Row flexWrap>
    <IconButton aria-label="Star"><Star /></IconButton>
    <IconButton secondary aria-label="Favorite"><Heart /></IconButton>
    <IconButton success aria-label="Confirm"><Check /></IconButton>
    <IconButton danger aria-label="Delete"><Trash2 /></IconButton>
    <IconButton warning aria-label="Notify"><Bell /></IconButton>
    <IconButton info aria-label="Info"><Info /></IconButton>
  </Row>
  <Row flexWrap>
    <IconButton filled aria-label="Star"><Star /></IconButton>
    <IconButton filled secondary aria-label="Favorite"><Heart /></IconButton>
    <IconButton filled success aria-label="Confirm"><Check /></IconButton>
    <IconButton filled danger aria-label="Delete"><Trash2 /></IconButton>
    <IconButton filled warning aria-label="Notify"><Bell /></IconButton>
    <IconButton filled info aria-label="Info"><Info /></IconButton>
  </Row>
</Col>

Shapes

IconButton supports rounded (default), pill, and sharp. pill is especially well suited to icon-only buttons.

rounded

pill

sharp

<Row flexWrap>
  <Col itemsCenter>
    <IconButton filled aria-label="Star rounded"><Star /></IconButton>
    <Text sm secondary>rounded</Text>
  </Col>
  <Col itemsCenter>
    <IconButton pill filled aria-label="Star pill"><Star /></IconButton>
    <Text sm secondary>pill</Text>
  </Col>
  <Col itemsCenter>
    <IconButton sharp filled aria-label="Star sharp"><Star /></IconButton>
    <Text sm secondary>sharp</Text>
  </Col>
</Row>

As Link & Disabled

Pass href to render the IconButton as an <a> for navigation. Use disabled to prevent interaction.

<Row flexWrap>
  <IconButton href="https://github.com" target="_blank" aria-label="GitHub"><ExternalLink /></IconButton>
  <IconButton filled success href="#" aria-label="Open"><ExternalLink /></IconButton>
  <IconButton disabled aria-label="Save disabled"><Star /></IconButton>
  <IconButton filled danger disabled aria-label="Delete disabled"><Trash2 /></IconButton>
</Row>

Next.js Link Integration

Use the tag prop to render the IconButton as a Next.js Link for client-side navigation.

import Link from 'next/link';
import { IconButton } from '@vaneui/ui';
import { Settings } from 'react-feather';

<IconButton href="/settings" tag={Link} aria-label="Settings"><Settings /></IconButton>

Loading State

Set loading to show a spinner and auto-disable the button.

const [loading, setLoading] = useState(false);

<IconButton loading={loading} onClick={() => setLoading(true)} aria-label="Save">
  <Star />
</IconButton>

Customizing

Set app-wide IconButton defaults with ThemeProvider's themeDefaults:

import { ThemeProvider, IconButton } from '@vaneui/ui';

<ThemeProvider themeDefaults={{
  iconButton: { secondary: true, pill: true, lg: true },
}}>
  <IconButton aria-label="Star"><Star /></IconButton>
</ThemeProvider>

IconButton Props

Prop	Category	Default	Description
`accent`	Appearance		Accent color appearance (rose)
`brand`	Appearance		Brand color appearance (blue)
`danger`	Appearance		Danger color appearance (red)
`info`	Appearance		Info color appearance (cyan)
`inherit`	Appearance		Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables
`link`	Appearance		Link color appearance (blue, for hyperlinks)
`primary`	Appearance	✓	Primary color appearance (gray)
`secondary`	Appearance		Secondary color appearance (gray)
`success`	Appearance		Success color appearance (green)
`tertiary`	Appearance		Tertiary color appearance
`warning`	Appearance		Warning color appearance (amber)
`disabled`	Disabled		Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction
`flex1`	Flex		Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`)
`flexAuto`	Flex		Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`)
`flexNone`	Flex		Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`)
`heading`	Font Family		Heading font family (defaults to sans, independently customizable via --font-heading CSS variable)
`mono`	Font Family		Monospace font family
`sans`	Font Family		Sans-serif font family (default)
`serif`	Font Family		Serif font family
`italic`	Font Style		Italic font style
`notItalic`	Font Style		Not italic (normal) font style
`black`	Font Weight		Black font weight (900)
`bold`	Font Weight		Bold font weight (700)
`extrabold`	Font Weight		Extra bold font weight (800)
`extralight`	Font Weight		Extra light font weight (200)
`light`	Font Weight		Light font weight (300)
`medium`	Font Weight		Medium font weight (500)
`normal`	Font Weight		Normal font weight (400)
`semibold`	Font Weight		Semibold font weight (600)
`thin`	Font Weight		Thin font weight (100)
`inheritSize`	Inherit Size		Inherit font-size and line-height from the nearest parent typography element
`noInheritSize`	Inherit Size		Keep own font-size; do not inherit from parent
`noPadding`	Padding		Disable internal padding
`padding`	Padding	✓	Enable internal padding
`paddingX`	Padding		Enable only horizontal padding
`paddingY`	Padding		Enable only vertical padding
`pill`	Shape		Fully rounded corners (circular)
`rounded`	Shape	✓	Medium rounded corners (default)
`sharp`	Shape		No rounded corners (square)
`noShrink`	Shrink		Prevent the flex item from shrinking below its content size (= `shrink-0`)
`lg`	Size		Large size
`md`	Size	✓	Medium size (default)
`sm`	Size		Small size
`xl`	Size		Extra large size
`xs`	Size		Extra small size
`textCenter`	Text Align		Align text to center
`textJustify`	Text Align		Justify text
`textLeft`	Text Align		Align text to left
`textRight`	Text Align		Align text to right
`lineThrough`	Text Decoration		Add strikethrough/line-through decoration across text
`noUnderline`	Text Decoration		Remove text decoration (no underline, strikethrough, etc.)
`overline`	Text Decoration		Add overline decoration above text
`underline`	Text Decoration		Add underline decoration below text
`capitalize`	Text Transform		Capitalize first letter of each word
`lowercase`	Text Transform		Transform text to lowercase
`normalCase`	Text Transform		Normal text case (no transformation)
`uppercase`	Text Transform		Transform text to uppercase
`filled`	Variant		Filled variant - solid background with contrasting text color
`ghost`	Variant		Ghost variant - transparent background, no border, appearance-colored text, tinted hover background
`outline`	Variant	✓	Outline variant - transparent background with border and colored text (default)

Layout & utility props (gap, padding, hide, items, justify, ...) — documented on Common Props

Prop	Category	Default	Description
`border`	Border		Enable border on all sides
`borderB`	Border		Enable border on bottom
`borderL`	Border		Enable border on left
`borderR`	Border		Enable border on right
`borderT`	Border		Enable border on top
`borderX`	Border		Enable border on left and right
`borderY`	Border		Enable border on top and bottom
`noBorder`	Border	✓	Disable all borders
`cursorDefault`	Cursor		Default cursor - standard arrow
`cursorMove`	Cursor		Move cursor - indicates draggable element
`cursorNone`	Cursor		No cursor - hides the cursor
`cursorNotAllowed`	Cursor		Not-allowed cursor - indicates disabled state
`cursorPointer`	Cursor	✓	Pointer cursor - indicates clickable element
`cursorText`	Cursor		Text cursor - indicates selectable text
`cursorWait`	Cursor		Wait cursor - indicates loading/processing
`block`	Display		Block display - takes full width, new line
`contents`	Display		Contents display - element's box is removed, children display as if parent didn't exist
`flex`	Display		Flex display - flexbox container
`grid`	Display		Grid display - CSS grid container
`hidden`	Display		Hidden display - element is not visible
`inline`	Display		Inline display - flows with text
`inlineBlock`	Display		Inline-block display - inline but with block properties
`inlineFlex`	Display	✓	Inline-flex display - inline flexbox container
`inlineGrid`	Display		Inline-grid display - inline grid container
`table`	Display		Table display - behaves like table element
`tableCell`	Display		Table-cell display - behaves like td element
`column`	Flex Direction		Flex direction column (vertical)
`columnReverse`	Flex Direction		Flex direction column-reverse
`row`	Flex Direction		Flex direction row (horizontal)
`rowReverse`	Flex Direction		Flex direction row-reverse
`focusVisible`	Focus Visible	✓	Enable focus-visible outline
`noFocusVisible`	Focus Visible		Disable focus-visible outline
`gap`	Gap		Enable gap spacing between children
`noGap`	Gap		Disable gap spacing
`hAuto`	Height		Set height to auto
`hFit`	Height	✓	Set height to fit-content
`hFull`	Height		Set height to 100%
`hScreen`	Height		Set height to 100vh (viewport height), removes max-height constraint
`desktopHide`	Hide		Hide element on desktop devices and below (max-desktop: 80rem)
`mobileHide`	Hide		Hide element on mobile devices and below (max-mobile: 48rem)
`tabletHide`	Hide		Hide element on tablet devices and below (max-tablet: 64rem)
`itemsBaseline`	Items		Align items to baseline
`itemsCenter`	Items	✓	Align items to center
`itemsEnd`	Items		Align items to end (bottom/right)
`itemsStart`	Items		Align items to start (top/left)
`itemsStretch`	Items		Stretch items to fill container
`justifyAround`	Justify		Distribute items with space around them
`justifyBaseline`	Justify		Align items along their baseline on main axis
`justifyBetween`	Justify		Distribute items with space between them
`justifyCenter`	Justify	✓	Center items along the main axis
`justifyEnd`	Justify		Pack items toward the end of the main axis
`justifyEvenly`	Justify		Distribute items with equal space around them
`justifyStart`	Justify		Pack items toward the start of the main axis
`justifyStretch`	Justify		Stretch items to fill the main axis
`overflowAuto`	Overflow		Auto overflow - show scrollbars if needed
`overflowClip`	Overflow		Clip overflow - hard clip without scrollbars
`overflowHidden`	Overflow		Hidden overflow - clip content without scrollbars
`overflowScroll`	Overflow		Scroll overflow - always show scrollbars
`overflowVisible`	Overflow		Visible overflow - content extends beyond bounds
`overflowXAuto`	Overflow		Auto overflow on X-axis only
`overflowXClip`	Overflow		Clip overflow on X-axis only
`overflowXHidden`	Overflow		Hidden overflow on X-axis only
`overflowXScroll`	Overflow		Scroll overflow on X-axis only
`overflowXVisible`	Overflow		Visible overflow on X-axis only
`overflowYAuto`	Overflow		Auto overflow on Y-axis only
`overflowYClip`	Overflow		Clip overflow on Y-axis only
`overflowYHidden`	Overflow		Hidden overflow on Y-axis only
`overflowYScroll`	Overflow		Scroll overflow on Y-axis only
`overflowYVisible`	Overflow		Visible overflow on Y-axis only
`absolute`	Position		Absolute positioning
`fixed`	Position		Fixed positioning
`relative`	Position		Relative positioning
`static`	Position		Static positioning
`sticky`	Position		Sticky positioning
`responsive`	Responsive		Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap
`reverse`	Reverse		Reverse the order of children
`noRing`	Ring		Disable focus ring
`ring`	Ring	✓	Enable focus ring
`noShadow`	Shadow		Disable drop shadow
`shadow`	Shadow		Enable drop shadow
`noTransition`	Transition		Disable transitions for instant state changes
`transition`	Transition	✓	Enable smooth transitions between states
`transparent`	Transparent		Disable background color - makes component background transparent
`whitespaceBreakSpaces`	Whitespace		Break words to prevent overflow
`whitespaceNormal`	Whitespace		Normal wrapping - default browser behavior
`whitespaceNowrap`	Whitespace		No wrap - text stays on single line
`whitespacePre`	Whitespace		Preserve whitespace and line breaks
`whitespacePreLine`	Whitespace		Preserve line breaks, collapse spaces, wrap text
`whitespacePreWrap`	Whitespace		Preserve whitespace, wrap text
`wAuto`	Width		Set width to auto
`wFit`	Width		Set width to fit-content
`wFull`	Width		Set width to 100%
`wScreen`	Width		Set width to 100vw (viewport width), removes max-width constraint
`flexNoWrap`	Wrap		Force flex items to stay on single line (may overflow)
`flexWrap`	Wrap		Allow flex items to wrap to new lines when container is too narrow
`flexWrapReverse`	Wrap		Wrap flex items in reverse order (last items wrap first)