Documentation Playground
Skip to content
Docs

Icon Button

Button designed specifically for usage with a single icon. 
<.icon_button aria-label="Search">
  <svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  >
    <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
  </svg>
</.icon_button>

API Reference

This component is based on the button element and supports common margin props.

Prop Type Default Description
as string "button" Render as button or a tag.
class string nil Additional CSS classes.
color string — Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
disabled boolean false Disabled state.
high_contrast boolean — Whether to increase color contrast with the background.
loading boolean false Show loading spinner (API only).
m any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mb any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
ml any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mr any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mt any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
mx any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
my any — Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
p any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
pb any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
pl any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
pr any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
pt any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
px any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
py any — Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
radius string — Border radius utility. Accepts: none, small, medium, large, full. Responsive supported.
size string "2" Button size.
style string nil Additional inline styles.
type string "button" Button type.
variant string "soft" Button style variant.
as Render as button or a tag.
Type string Default "button"
class Additional CSS classes.
Type string Default nil
color Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
Type string Default —
disabled Disabled state.
Type boolean Default false
high_contrast Whether to increase color contrast with the background.
Type boolean Default —
loading Show loading spinner (API only).
Type boolean Default false
m Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mb Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
ml Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mr Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mt Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
mx Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
my Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
p Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
pb Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
pl Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
pr Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
pt Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
px Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
py Padding utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type any Default —
radius Border radius utility. Accepts: none, small, medium, large, full. Responsive supported.
Type string Default —
size Button size.
Type string Default "2"
style Additional inline styles.
Type string Default nil
type Button type.
Type string Default "button"
variant Button style variant.
Type string Default "soft"

Examples

Size

Use the size prop to control the size of the button.

<.flex align="center" gap="3">
  <.icon_button size="1" variant="soft" aria-label="Search">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="15"
      height="15"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    >
      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
    </svg>
  </.icon_button><.icon_button size="2" variant="soft" aria-label="Search"><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    size="3"
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="22"
    height="22"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
</.flex>

Variant

Use the variant prop to control the visual style of the button.

<.flex gap="3">
  <.icon_button variant="classic" aria-label="Search">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    >
      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
    </svg>
  </.icon_button><.icon_button variant="solid" aria-label="Search"><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    variant="surface"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    variant="outline"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
</.flex>

Ghost

Use the ghost variant to display a button without chrome. Ghost buttons behave like text in layout, as they use a negative margin to optically align themselves against their siblings while maintaining the padding in active and hover states.

<.icon_button variant="ghost" aria-label="Search">
  <svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  >
    <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
  </svg>
</.icon_button>

Color

Use the color prop to assign a specific accent color.

<.flex gap="3">
  <.icon_button color="crimson" variant="soft" aria-label="Search">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    >
      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
    </svg>
  </.icon_button><.icon_button color="indigo" variant="soft" aria-label="Search"><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    color="grass"
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    color="orange"
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
</.flex>

High-contrast

Use the high_contrast prop to increase color contrast with the background.

<.flex direction="column" gap="3">
  <.flex gap="3">
    <.icon_button color="gray" variant="classic" aria-label="Search">
      <svg
        xmlns="http://www.w3.org/2000/svg"
        width="18"
        height="18"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        stroke-width="2"
        stroke-linecap="round"
        stroke-linejoin="round"
      >
        <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
      </svg>
    </.icon_button><.icon_button color="gray" variant="solid" aria-label="Search"><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="soft"
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="surface"
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="outline"
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
  </.flex>
  <.flex gap="3">
    <.icon_button color="gray" variant="classic" high_contrast aria-label="Search">
      <svg
        xmlns="http://www.w3.org/2000/svg"
        width="18"
        height="18"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        stroke-width="2"
        stroke-linecap="round"
        stroke-linejoin="round"
      >
        <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
      </svg>
    </.icon_button><.icon_button color="gray" variant="solid" high_contrast aria-label="Search"><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="soft"
      high_contrast
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="surface"
      high_contrast
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
      color="gray"
      variant="outline"
      high_contrast
      aria-label="Search"
    ><svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
  </.flex>
</.flex>

Radius

Use the radius prop to assign a specific radius value.

<.flex gap="3">
  <.icon_button radius="none" variant="soft" aria-label="Search">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    >
      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
    </svg>
  </.icon_button><.icon_button radius="large" variant="soft" aria-label="Search"><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    radius="full"
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
</.flex>

Loading

Use the loading prop to display a loading spinner in place of button content. The button will be disabled while loading.

<.flex gap="3">
  <.icon_button loading variant="classic" aria-label="Search">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="18"
      height="18"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
    >
      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
    </svg>
  </.icon_button><.icon_button loading variant="solid" aria-label="Search"><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    loading
    variant="soft"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    loading
    variant="surface"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button><.icon_button
    loading
    variant="outline"
    aria-label="Search"
  ><svg
    xmlns="http://www.w3.org/2000/svg"
    width="18"
    height="18"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  ><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg></.icon_button>
</.flex>
← Hover Card Popover →