Button
Versatile button with multiple variants, sizes, icon support, loading state, and automatic tooltip integration.
import { Button } from "phoundry-ui";Variants
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui";</script>
<div class="flex flex-wrap items-center gap-2"> <Button variant="primary">Primary</Button> <Button variant="secondary">Secondary</Button> <Button variant="outline">Outline</Button> <Button variant="danger">Danger</Button> <Button variant="ghost">Ghost</Button> <Button variant="link">Link</Button></div>Sizes
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<div class="flex items-center gap-2"> <Button size="xs">Extra Small</Button> <Button size="sm">Small</Button> <Button size="md">Medium</Button> <Button size="lg">Large</Button></div><div class="mt-2 flex items-center gap-2"> <Button icon={PhiIcons.add} size="xs">Extra Small</Button> <Button icon={PhiIcons.info} size="sm">Small</Button> <Button icon={PhiIcons.edit} size="md">Medium</Button> <Button icon={PhiIcons.add} size="lg">Large</Button></div>With Icons
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<div class="flex items-center gap-2"> <Button icon={PhiIcons.add} variant="primary">Add Item</Button> <Button icon={PhiIcons.edit} iconPosition="right">Settings</Button> <Button icon={PhiIcons.close} title="Close" tooltipPlacement="right" /></div>States
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<div class="flex items-center gap-2"> <Button loading>Saving...</Button> <Button active>Active</Button> <Button variant="outline" icon={PhiIcons.folder} active>Add Folder</Button> <Button disabled>Disabled</Button></div>Full width
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<div class="w-64 space-y-2"> <Button variant="primary" fullWidth>Continue</Button> <Button variant="outline" fullWidth icon={PhiIcons.add}>Add item</Button></div>As Link
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui";</script>
<Button href="https://example.com" target="_blank" variant="link" >External Link</Button>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
variant | ButtonVariant | 'secondary' | Visual style of the button. |
size | ButtonSize | 'md' | Canonical control scale - heights, typography, padding, and icon px shared via CSS custom properties. |
icon | string | — | Iconify icon string shown alongside or instead of text. |
iconPosition | "left" | "right" | 'left' | Which side to place the icon on. |
loading | boolean | false | Show a spinner and disable interaction. |
active | boolean | — | Highlight the button as currently active/selected. |
disabled | boolean | null | false | Disable the button. |
class | ClassValue | — | Additional CSS classes merged onto the outer interactive element. |
elementbindable | HTMLButtonElement | HTMLAnchorElement | — | Bindable reference to the underlying button or anchor. |
href | any | — | When provided, renders an <a> tag instead of <button>. |
target | string | — | Link target when using href (e.g. _blank). |
rel | string | — | Optional link rel; defaults to noopener noreferrer when target is _blank. |
title | string | — | Tooltip text (uses the phoundry-ui tooltip system by default). |
noTooltip | boolean | false | Use native title attribute instead of tooltip system. |
tooltipPlacement | TooltipPlacement | 'top' | Placement for the automatic title tooltip. Accepts follow-cursor or any PopoverPlacement value. |
fullWidth | boolean | false | Stretch the button to the width of its parent. |
onclick | (e: MouseEvent) => void | — | Click handler. |
children | Snippet<[]> | — | Button label content. |
Other native attributes: Other native attributes (type, aria-, data-, keyboard handlers, etc.) are forwarded to the DOM element.
Usage tips
- Omit children for icon-only buttons and supply
aria-labelortitlefor the accessible name. - Use
tooltipPlacementto anchor the automatic tooltip to the button; the default placement istop. - Set
noTooltipto use the native browser title attribute instead of the phoundry-ui tooltip system. - The
linkvariant removes height and padding - it renders inline like a text link. ButtonGroupsupports text and icon segments inside an inset, rounded shell.
Link and loading semantics
A linked Button prevents activation while disabled or loading, and exposes aria-disabled. Button toggle semantics (aria-pressed) apply to native buttons. Loading-only buttons infer icon-only geometry. When target="_blank" is supplied without an explicit rel, Button supplies noopener noreferrer; explicit rel values are preserved.
CSS customization
The stable root is .ph-btn. Variant and size use data-variant and data-size;
icon-only layout is derived from an icon or spinner and the absence of children.
iconOnly has been removed. Width uses fullWidth or Consumer CSS. Shared
--ph-comp-h-*, --ph-comp-icon-*, --ph-btn-radius, --ph-button-shadow,
--ph-button-specular, --ph-button-shading, and --ph-text-shadow properties
provide supported customization. Internal part selectors and --_ph-* values
are implementation details.
Keyboard focus uses the hover treatment without a default ring. Persistent active state uses the item-selection foreground/background hooks; native pressed state uses the variant’s pressed treatment. .ph-btn-label and .ph-btn-icon are supported theme parts alongside .ph-btn. Use :root .ph-btn for an ordinary CSS root override with matching scoped-style specificity, or documented public custom properties.