IconButton

IconButton is a compact, icon-only button component. It requires an aria-label for accessibility.

Open in Storybook

Import

import { IconButton } from "@tosui/react";

Basic usage

Preview

Code

import { EditIcon } from "your-icon-library";

<IconButton icon={<EditIcon />} aria-label="Edit item" />

Variants

<HStack gap={4}>
  <IconButton variant="solid" icon={<EditIcon />} aria-label="Edit" />
  <IconButton variant="outline" icon={<EditIcon />} aria-label="Edit" />
  <IconButton variant="ghost" icon={<EditIcon />} aria-label="Edit" />
</HStack>

Sizes

<HStack gap={4} align="center">
  <IconButton size="sm" icon={<EditIcon />} aria-label="Edit" />
  <IconButton size="md" icon={<EditIcon />} aria-label="Edit" />
  <IconButton size="lg" icon={<EditIcon />} aria-label="Edit" />
</HStack>

Color schemes

<HStack gap={4}>
  <IconButton colorScheme="primary" icon={<StarIcon />} aria-label="Favorite" />
  <IconButton colorScheme="accent" icon={<StarIcon />} aria-label="Favorite" />
  <IconButton colorScheme="success" icon={<CheckIcon />} aria-label="Approve" />
  <IconButton colorScheme="warning" icon={<AlertIcon />} aria-label="Warning" />
  <IconButton colorScheme="error" icon={<TrashIcon />} aria-label="Delete" />
  <IconButton colorScheme="info" icon={<InfoIcon />} aria-label="Info" />
</HStack>

Variants with color schemes

<VStack gap={4}>
  <HStack gap={4}>
    <IconButton variant="solid" colorScheme="error" icon={<TrashIcon />} aria-label="Delete" />
    <IconButton variant="outline" colorScheme="error" icon={<TrashIcon />} aria-label="Delete" />
    <IconButton variant="ghost" colorScheme="error" icon={<TrashIcon />} aria-label="Delete" />
  </HStack>
</VStack>

States

<HStack gap={4}>
  <IconButton icon={<EditIcon />} aria-label="Edit" />
  <IconButton icon={<EditIcon />} aria-label="Edit" disabled />
  <IconButton icon={<EditIcon />} aria-label="Edit" loading />
</HStack>

Common patterns

Toolbar actions

<HStack gap={2} p={2} bg="surface" rounded="md">
  <IconButton variant="ghost" icon={<BoldIcon />} aria-label="Bold" />
  <IconButton variant="ghost" icon={<ItalicIcon />} aria-label="Italic" />
  <IconButton variant="ghost" icon={<UnderlineIcon />} aria-label="Underline" />
  <Divider orientation="vertical" h="24px" />
  <IconButton variant="ghost" icon={<LinkIcon />} aria-label="Insert link" />
  <IconButton variant="ghost" icon={<ImageIcon />} aria-label="Insert image" />
</HStack>

Card actions

<Card>
  <CardBody>
    <HStack justify="space-between">
      <Box>
        <Heading size="lg">Item Title</Heading>
        <Text color="foreground-muted">Item description</Text>
      </Box>
      <HStack gap={1}>
        <IconButton
          variant="ghost"
          icon={<EditIcon />}
          aria-label="Edit item"
        />
        <IconButton
          variant="ghost"
          colorScheme="error"
          icon={<TrashIcon />}
          aria-label="Delete item"
        />
      </HStack>
    </HStack>
  </CardBody>
</Card>

Close button

<Box position="relative" p={4} bg="surface" rounded="md">
  <Box
    position="absolute"
    top={2}
    right={2}
  >
    <IconButton
      variant="ghost"
      icon={<CloseIcon />}
      aria-label="Close"
    />
  </Box>
  <Text>Modal or alert content</Text>
</Box>

Pagination controls

<HStack gap={2}>
  <IconButton icon={<ChevronLeftIcon />} aria-label="Previous page" />
  <Text>Page 1 of 10</Text>
  <IconButton icon={<ChevronRightIcon />} aria-label="Next page" />
</HStack>

Props reference

Prop	Type	Default	Description
icon	ReactNode	-	The icon to display (required)
aria-label	string	-	Accessible label (required)
variant	"solid" | "outline" | "ghost"	"solid"	Visual variant
size	"sm" | "md" | "lg"	"md"	Button size
colorScheme	"primary" | "accent" | "success" | "warning" | "error" | "info"	"primary"	Color scheme
disabled	boolean	false	Disable the button
loading	boolean	false	Show loading spinner
onClick	() => void	-	Click handler
className	string	-	Additional CSS class

Size dimensions

Size	Dimensions
sm	28px x 28px
md	36px x 36px
lg	44px x 44px

Accessibility

• aria-label is required because IconButton has no visible text.
• The icon wrapper uses aria-hidden="true" because aria-label supplies the accessible name.
• Native button behavior supports Enter and Space.

TypeScript

import { IconButton, type IconButtonVariant, type IconButtonSize, type IconButtonColorScheme, type IconButtonProps } from "@tosui/react";