Icon Button — ARC UI

Components

Icon Button

input

hybrid

<arc-icon-button>

Overview

Guidelines

When to use

Always provide a `label` or `text` prop so the button has an accessible name for screen readers
Use the `ghost` variant for secondary or tertiary actions in toolbars to reduce visual noise
Use `href` for navigation actions so the element renders as a semantic anchor tag
Match the `size` to surrounding elements -- use `xs` or `sm` in dense UIs like table rows
Pair with `arc-tooltip` to explain icon-only buttons on hover

When not to use

Do not use IconButton for primary page actions that need a full-width call to action -- use Button instead
Do not omit the `label` prop on icon-only buttons -- they will be invisible to assistive technology
Do not combine `disabled` with `href` -- anchor tags cannot be natively disabled
Do not use long `text` values -- the uppercase styling and compact padding are designed for 1-2 word labels
Avoid placing many `primary` variant icon buttons in the same row -- reserve the solid fill for the single most important action

Features

Three visual variants: ghost (default transparent), secondary (bordered with blue glow), and primary (solid accent fill)
Four sizes -- xs (28px), sm (32px), md (36px), lg (44px) -- with automatic icon size mapping
Optional `text` prop that expands the button from a square icon into a labeled action button with uppercase styling
Renders as an `<a>` tag when `href` is provided, enabling accessible navigation links
Active-press animation with `scale(0.93)` transform for tactile feedback
Built-in `arc-icon` integration via the `name` prop, or custom content via the default slot
Focus-visible glow ring using the shared `--focus-glow` token for keyboard navigation
Accessible `aria-label` derived automatically from `label`, `text`, or manual override

Preview

Usage

Layout and styling work without JavaScript via the HTML/CSS versions. Interactive features like events and state management require the Web Component or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<!-- Toolbar with mixed variants -->
<div style="display:flex; gap:8px; align-items:center;">
  <arc-icon-button name="pencil" label="Edit" variant="ghost"></arc-icon-button>
  <arc-icon-button name="copy" label="Duplicate" variant="ghost"></arc-icon-button>
  <arc-icon-button name="trash" label="Delete" variant="ghost"></arc-icon-button>
  <arc-icon-button name="share" label="Share" variant="secondary"></arc-icon-button>
  <arc-icon-button name="plus" text="New Item" variant="primary"></arc-icon-button>
</div>

<!-- Sizes -->
<div style="display:flex; gap:8px; align-items:center; margin-top:16px;">
  <arc-icon-button name="star" label="Favorite" size="xs"></arc-icon-button>
  <arc-icon-button name="star" label="Favorite" size="sm"></arc-icon-button>
  <arc-icon-button name="star" label="Favorite" size="md"></arc-icon-button>
  <arc-icon-button name="star" label="Favorite" size="lg"></arc-icon-button>
</div>

<!-- Navigation link -->
<arc-icon-button name="gear" text="Settings" variant="secondary" href="/settings"></arc-icon-button>

import { IconButton } from '@arclux/arc-ui-react';

function DocumentToolbar({ onSave, onDelete }) {
  return (
    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
      <IconButton name="pencil" label="Edit" />
      <IconButton name="copy" label="Duplicate" />
      <IconButton name="download" label="Download" variant="secondary" />
      <IconButton name="trash" label="Delete" variant="secondary"
        onClick={onDelete} />
      <IconButton name="floppy-disk" text="Save" variant="primary"
        onClick={onSave} />
    </div>
  );
}

function SocialActions() {
  return (
    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
      <IconButton name="heart" label="Like" size="lg" variant="primary" />
      <IconButton name="share" label="Share" size="lg" variant="secondary" />
      <IconButton name="bookmark" label="Bookmark" size="lg" />
    </div>
  );
}

<script setup>
import { IconButton } from '@arclux/arc-ui-vue';

function handleEdit() { console.log('Editing...'); }
function handleDelete() { console.log('Deleting...'); }
</script>

<template>
  <!-- Card action bar -->
  <div style="display:flex; gap:8px; align-items:center;">
    <IconButton name="pencil" label="Edit" @click="handleEdit" />
    <IconButton name="copy" label="Duplicate" variant="ghost" />
    <IconButton name="trash" label="Delete" variant="secondary" @click="handleDelete" />
  </div>

  <!-- With text labels for clarity -->
  <div style="display:flex; gap:8px; align-items:center; margin-top:16px;">
    <IconButton name="download" text="Export" variant="secondary" />
    <IconButton name="share" text="Share" variant="ghost" />
    <IconButton name="plus" text="Add" variant="primary" />
  </div>
</template>

<script>
  import { IconButton } from '@arclux/arc-ui-svelte';

  let liked = false;
</script>

<!-- Toggle-style icon button -->
<IconButton
  name={liked ? 'heart-fill' : 'heart'}
  label={liked ? 'Unlike' : 'Like'}
  variant={liked ? 'primary' : 'ghost'}
  on:click={() => liked = !liked}
/>

<!-- Compact toolbar -->
<div style="display:flex; gap:4px;">
  <IconButton name="pencil" label="Edit" size="sm" />
  <IconButton name="copy" label="Copy" size="sm" />
  <IconButton name="link" label="Copy Link" size="sm" />
  <IconButton name="trash" label="Delete" size="sm" variant="secondary" />
</div>

import { Component } from '@angular/core';
import { IconButton } from '@arclux/arc-ui-angular';

@Component({
  imports: [IconButton],
  template: `
    <div style="display:flex; gap:8px; align-items:center;">
      <IconButton name="pencil" label="Edit" (click)="onEdit()"></IconButton>
      <IconButton name="copy" label="Duplicate" variant="ghost"></IconButton>
      <IconButton name="trash" label="Delete" variant="secondary" (click)="onDelete()"></IconButton>
      <IconButton name="plus" text="New Item" variant="primary" (click)="onCreate()"></IconButton>
    </div>

    <!-- Navigation links -->
    <div style="display:flex; gap:8px; margin-top:16px;">
      <IconButton name="gear" text="Settings" variant="secondary" href="/settings"></IconButton>
      <IconButton name="bell" text="Notifications" variant="ghost" href="/notifications"></IconButton>
    </div>
  `,
})
export class ToolbarComponent {
  onEdit() { console.log('Edit'); }
  onDelete() { console.log('Delete'); }
  onCreate() { console.log('Create'); }
}

import { IconButton } from '@arclux/arc-ui-solid';

function TableRowActions(props: { onEdit: () => void; onDelete: () => void }) {
  return (
    <div style={{ display: 'flex', gap: '4px' }}>
      <IconButton name="pencil" label="Edit" size="xs" onClick={props.onEdit} />
      <IconButton name="copy" label="Duplicate" size="xs" />
      <IconButton name="trash" label="Delete" size="xs" variant="secondary" onClick={props.onDelete} />
    </div>
  );
}

function PageHeader() {
  return (
    <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
      <IconButton name="arrow-left" label="Back" href="/" />
      <IconButton name="share" text="Share" variant="secondary" />
      <IconButton name="download" text="Export" variant="primary" />
    </div>
  );
}

import { IconButton } from '@arclux/arc-ui-preact';

function MediaControls() {
  return (
    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
      <IconButton name="skip-back" label="Previous" size="sm" />
      <IconButton name="play" label="Play" variant="primary" size="lg" />
      <IconButton name="skip-forward" label="Next" size="sm" />
      <IconButton name="speaker-high" label="Volume" size="sm" variant="ghost" />
      <IconButton name="heart" label="Favorite" size="sm" />
    </div>
  );
}

<!-- arc-icon-button is interactive — requires JS -->
<arc-icon-button></arc-icon-button>

<!-- Auto-generated by @arclight/prism — do not edit manually -->
<!-- arc-icon-button — requires icon-button.css + tokens.css (or arc-ui.css) -->
<span class="arc-icon-button">
  <a href="#" aria-label="Label"></a>
</span>

API

Prop	Type	Default	Description
`name`	`string`	`''`	Name of the arc-icon to render. When empty, the default slot is used for custom icon content.
`text`	`string`	`''`	Optional text label displayed next to the icon. When provided, the button expands from a square to a wider labeled button with uppercase styling.
`variant`	`'ghost' \| 'secondary' \| 'primary'`	`'ghost'`	Visual style variant. Ghost is transparent, secondary has a border with glow, primary has a solid accent-primary fill.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`	Button size controlling dimensions and icon scale. Icon-only sizes: xs=28px, sm=32px, md=36px, lg=44px.
`label`	`string`	`''`	Accessible label for the button. Falls back to `text` if not provided. Required for icon-only usage.
`href`	`string`	`''`	When set, renders the button as an anchor tag for navigation links.
`disabled`	`boolean`	`false`	Disables the button, reducing opacity to 40% and blocking pointer events.
`type`	`string`	`'button'`	HTML button type attribute. Only applies when `href` is not set.