# Button — SvelteKit UI

Package: sveltekit-ui 1.1.91

Page: https://www.sveltekit-ui.com/components/button

Category: Foundations

creates a fully customizable button with optional icon, interactive states, and configurable styling

Public component import: `Button`

Public manager import: `create_button_manager`

## Usage

```svelte
<script>
  // Import the shared stylesheet once in your application's root layout.
  import "sveltekit-ui/style.css"
  import { Button, create_button_manager } from "sveltekit-ui"

  let count = $state(0)

  const manager = create_button_manager({
    text: "Add one",
    support_icon: "plus",
    on_click: () => { count += 1 },
  })
</script>

<Button {manager} />
<p role="status">Count: {count}</p>
```

## Configuration

### `type`

- type: string
- default: primary
- description: visual style of the button (primary, outlined, soft, plain)

### `support_icon`

- type: string
- default: null
- description: icon identifier to display; if null, no icon is shown

### `is_icon_bg_tint`

- type: boolean
- default: false
- description: applies a tinted background behind the icon

### `icon_deg`

- type: number
- default: 0
- description: deg rotation for the icon

### `icon_sw`

- type: number
- default: 0
- description: icon stroke width setting

### `icon_size`

- type: number
- default: 1.8
- description: icon size in rem units

### `icon_ml`

- type: number
- default: 0
- description: icon's left margin in rem

### `icon_mr`

- type: number
- default: 0
- description: icon's right margin in rem

### `icon_pos`

- type: string
- default: right
- description: icon position (left or right)

### `is_icon_shimmyable`

- type: boolean
- default: false
- description: whether icon can shimmy on hover

### `icon_movement_stiffness`

- type: number
- default: 0.1
- description: movement stiffness for shimmy effect

### `icon_movement_damping`

- type: number
- default: 0.1
- description: movement damping for shimmy effect

### `aria_label`

- type: string
- default: null
- description: aria-label for accessibility

### `popover_target`

- type: string
- default: null
- description: css selector id for an associated popover

### `href`

- type: string
- default: null
- description: renders the button as a native link when set, preserving right-click/copy-link behavior

### `target`

- type: string
- default: null
- description: optional target attribute used when href is set

### `rel`

- type: string
- default: noopener noreferrer when target is _blank
- description: optional rel attribute used when href is set

### `download`

- type: string or boolean
- default: null
- description: optional download attribute used when href is set

### `is_no_wrap`

- type: boolean
- default: false
- description: prevents text from wrapping

### `is_word_break_all`

- type: boolean
- default: false
- description: forces text to break at any character

### `is_success_animation`

- type: boolean
- default: false
- description: if true, triggers a success animation/icon on click

### `ml`

- type: number
- default: 0
- description: margin-left (rem)

### `mr`

- type: number
- default: 0
- description: margin-right (rem)

### `mt`

- type: number
- default: 0
- description: margin-top (rem)

### `mb`

- type: number
- default: 0
- description: margin-bottom (rem)

### `pl`

- type: number
- default: 1.1
- description: padding-left (rem)

### `pr`

- type: number
- default: 1.1
- description: padding-right (rem)

### `pt`

- type: number
- default: 0.3
- description: padding-top (rem)

### `pb`

- type: number
- default: 0.3
- description: padding-bottom (rem)

### `border_radius`

- type: number
- default: 1
- description: button border radius (rem)

### `tabindex`

- type: number
- default: 0
- description: tabindex for focus navigation

### `is_prevent_default`

- type: boolean
- default: false
- description: prevents default on click event if true

### `is_stop_propagation`

- type: boolean
- default: false
- description: stops event propagation on click if true

### `min_height`

- type: number
- default: 3.4
- description: minimum height of the button (rem)

### `fixed_width`

- type: number
- default: null
- description: fixed width in rem

### `min_width`

- type: number
- default: null
- description: minimum width in rem

### `is_compressed`

- type: boolean
- default: false
- description: if true, sets button width to auto

### `is_pill`

- type: boolean
- default: false
- description: if true, button is fully rounded

### `is_uniform`

- type: boolean
- default: false
- description: if true, forces button height == width

### `cursor`

- type: string
- default: pointer
- description: cursor style (pointer, move, etc.)

### `text_align`

- type: string
- default: center
- description: how to align button text: left, center, or right

### `font_size`

- type: number
- default: 1.6
- description: font size in rem

### `line_height`

- type: number
- default: 1.2
- description: line-height for text

### `font_weight`

- type: number
- default: 400
- description: font weight (normal=400, bold=700, etc.)

### `text`

- type: string
- default: null
- description: text label for the button

### `is_loading`

- type: boolean
- default: false
- description: if true, a loading spinner replaces icon/text

### `is_disabled`

- type: boolean
- default: false
- description: disables the button if true

### `selected_type`

- type: string
- default: null
- description: visual marker (selected or half_selected) appended to the style

### `h`

- type: number
- default: null
- description: color hue index for advanced color customization

### `c`

- type: number
- default: null
- description: color chroma index for advanced color customization

### `l`

- type: number
- default: null
- description: color luminance index for advanced color customization

### `color`

- type: string
- default: null
- description: button base color (if not using derived defaults)

### `gradient_to_color`

- type: string
- default: null
- description: button gradient end color (if not using derived defaults)

### `gradient_turn`

- type: number
- default: 0.3
- description: turn value for the button's linear-gradient (0 to 1 is a full 360° turn)

### `contrast_color`

- type: string
- default: null
- description: text/icon color used on top of button background

### `border_color`

- type: string
- default: null
- description: border color when type is outlined or a border is forced

### `hover_shadow_color`

- type: string
- default: transparent
- description: shadow color on hover

### `hover_shadow_size`

- type: number
- default: 1
- description: shadow size on hover

### `on_click`

- type: function
- default: null
- description: callback triggered upon button click; a returned Promise drives the loading state and blocks repeated activation until it settles

### `on_hover`

- type: function
- default: null
- description: callback triggered on pointer enter/leave; receives true (enter) or false (leave)

### `is_simulated_active`

- type: boolean
- default: false
- description: if true, button is forced into an active state for visual effect

## Methods

### `success_trigger()`

- description: triggers a success state, displaying success icon for ~1.4s
- parameters:
- returns: void

### `error_trigger()`

- description: triggers an error state, displaying error icon for ~1.4s
- parameters:
- returns: void

### `icon_shimmy_trigger()`

- description: manually triggers the icon's shimmy animation if is_icon_shimmyable
- parameters:
- returns: void

### `handle_click()`

- description: internal click handler that runs callbacks while preserving the current native button activation
- parameters:
  - e: event
- returns: Promise<unknown>

### `pointer_down()`

- description: pointerdown event to set is_pointer_down to true
- parameters:
- returns: void

### `pointer_up()`

- description: pointerup event to reset is_pointer_down to false
- parameters:
- returns: void

### `pointer_enter()`

- description: pointerenter event to set is_hovered to true and invoke on_hover(true)
- parameters:
- returns: void

### `pointer_leave()`

- description: pointerleave event to set is_hovered to false and invoke on_hover(false)
- parameters:
- returns: void

### `simulate_click()`

- description: simulates a click, briefly showing the pressed state
- parameters:
- returns: void

### `focus()`

- description: programmatically sets focus to the button element
- parameters:
- returns: void

## Returned state

### `id`

- type: string
- description: unique identifier for this button instance

### `type`

- type: string
- description: the derived style type (primary, outlined, etc.)

### `ml`

- type: number
- description: margin-left in rem

### `mr`

- type: number
- description: margin-right in rem

### `mt`

- type: number
- description: margin-top in rem

### `mb`

- type: number
- description: margin-bottom in rem

### `pl`

- type: number
- description: padding-left in rem

### `pr`

- type: number
- description: padding-right in rem

### `pt`

- type: number
- description: padding-top in rem

### `pb`

- type: number
- description: padding-bottom in rem

### `border_radius`

- type: number
- description: button border radius in rem

### `is_loading`

- type: boolean
- description: shows a loading spinner if true

### `is_pointer_down`

- type: boolean
- description: true while pointer is pressed

### `is_prevent_default`

- type: boolean
- description: if true, prevents default event in handle_click

### `is_stop_propagation`

- type: boolean
- description: if true, stops event propagation in handle_click

### `tabindex`

- type: number
- description: button tabindex for keyboard focus

### `is_disabled`

- type: boolean
- description: true if the button is disabled

### `is_action_disabled`

- type: boolean
- description: true while disabled, loading, success, or error state blocks action

### `is_native_disabled`

- type: boolean
- description: true when the rendered button should use the native disabled attribute; waits for the current accepted activation to finish

### `selected_type`

- type: string
- description: selected or half_selected style variant

### `is_hovered`

- type: boolean
- description: true if pointer is hovering over the button

### `min_height`

- type: number
- description: minimum height in rem

### `fixed_width`

- type: number
- description: fixed button width in rem

### `min_width`

- type: number
- description: minimum button width in rem

### `is_compressed`

- type: boolean
- description: if true, sets width to auto

### `is_pill`

- type: boolean
- description: true if button is pill shaped

### `is_uniform`

- type: boolean
- description: true if button forces a uniform square shape

### `cursor`

- type: string
- description: current cursor style

### `text_align`

- type: string
- description: alignment for the text label

### `text`

- type: string
- description: current text label of the button

### `is_success_animation`

- type: boolean
- description: triggers success animation on click

### `font_size`

- type: number
- description: font size in rem

### `line_height`

- type: number
- description: text line-height

### `font_weight`

- type: number
- description: text font-weight

### `color`

- type: string
- description: base color for the button background

### `gradient_to_color`

- type: string
- description: secondary color for a gradient background

### `gradient_turn`

- type: number
- description: turn fraction for the linear gradient angle

### `contrast_color`

- type: string
- description: color used for text or icons on top of background

### `border_color`

- type: string
- description: border color if outlined or forced border is used

### `hover_shadow_color`

- type: string
- description: shadow color on hover

### `hover_shadow_size`

- type: number
- description: shadow size on hover

### `support_icon`

- type: string
- description: the icon identifier the button is currently set to display

### `is_icon_bg_tint`

- type: boolean
- description: true if there's a tinted background behind the icon

### `icon_deg`

- type: number
- description: rotation in degrees for the icon

### `icon_sw`

- type: number
- description: stroke width for the icon if applicable

### `icon_size`

- type: number
- description: icon size in rem

### `icon_ml`

- type: number
- description: icon left margin in rem

### `icon_mr`

- type: number
- description: icon right margin in rem

### `icon_pos`

- type: string
- description: icon position (left or right)

### `is_icon_shimmyable`

- type: boolean
- description: true if icon shakes when hovered

### `icon_movement_stiffness`

- type: number
- description: shimmy stiffness

### `icon_movement_damping`

- type: number
- description: shimmy damping

### `aria_label`

- type: string
- description: aria-label for accessibility

### `popover_target`

- type: string
- description: id for associated popover element

### `href`

- type: string
- description: native link href when the button renders as an anchor

### `target`

- type: string
- description: native link target when href is set

### `rel`

- type: string
- description: native link rel when href is set

### `download`

- type: string or boolean
- description: native link download attribute when href is set

### `is_link`

- type: boolean
- description: true when the button renders as an anchor

### `element_tag`

- type: string
- description: the rendered element tag, either button or a

### `is_no_wrap`

- type: boolean
- description: true if text should not wrap

### `is_word_break_all`

- type: boolean
- description: true if text can break at any character

### `is_simulated_active`

- type: boolean
- description: forces button into an active state visually

### `is_success`

- type: boolean
- description: true if button is showing success state

### `is_error`

- type: boolean
- description: true if button is showing error state

### `icon_manager`

- type: object
- description: the internally created icon manager for this button