carbon-components-svelte/src/Button/Button.svelte.d.ts

Svelte implementation of the Carbon Design System

import { SvelteComponentTyped } from "svelte";
import type { SvelteHTMLElements } from "svelte/elements";
import type { ButtonSkeletonProps } from "./ButtonSkeleton.svelte";

type $RestProps = SvelteHTMLElements["button"] & SvelteHTMLElements["a"] & SvelteHTMLElements["div"];

type $Props<Icon = any> = {
  /**
   * Specify the kind of button.
   * @default "primary"
   */
  kind?: "primary" | "secondary" | "tertiary" | "ghost" | "danger" | "danger-tertiary" | "danger-ghost";

  /**
   * Specify the size of button.
   * When the `badge` slot is used, size is set to `lg` per Carbon design guidelines.
   * @default "default"
   */
  size?: "default" | "field" | "small" | "lg" | "xl";

  /**
   * Set to `true` to use Carbon's expressive typesetting
   * @default false
   */
  expressive?: boolean;

  /**
   * Set to `true` to enable the selected state for an icon-only, ghost button.
   * @default false
   */
  isSelected?: boolean;

  /**
   * Specify the icon to render.
   * Alternatively, use the named slot "icon".
   * @example
   *  ```svelte
   *  <Button>
   *    <Icon slot="icon" size={20} />
   *  </Button>
   *  ```
   * @default undefined
   */
  icon?: Icon;

  /**
   * Specify the ARIA label for the button icon.
   * On an icon-only button, this also drives Carbon's tooltip. If omitted,
   * the icon-only button renders without a tooltip; supply your own
   * `aria-label` or `aria-labelledby` for accessibility in that case.
   * @default undefined
   */
  iconDescription?: string;

  /**
   * Set the alignment of the tooltip relative to the icon.
   * Only applies to icon-only buttons.
   * @default "center"
   */
  tooltipAlignment?: "start" | "center" | "end";

  /**
   * Set the position of the tooltip relative to the icon.
   * @default "bottom"
   */
  tooltipPosition?: "top" | "right" | "bottom" | "left";

  /**
   * Set to `true` to hide the tooltip while maintaining accessibility.
   * Only applies to icon-only buttons.
   * When `true`, the tooltip is visually hidden but the `iconDescription` remains accessible to screen readers.
   * @default false
   */
  hideTooltip?: boolean;

  /**
   * Set to `true` to render a custom HTML element.
   * Props are destructured as `props` in the default slot.
   * @example
   *  ```svelte
   *  <Button let:props>
   *    <div {...props}>Custom Element</div>
   *  </Button>
   *  ```
   * @default false
   */
  as?: boolean;

  /**
   * Set to `true` to display the skeleton state
   * @default false
   */
  skeleton?: boolean;

  /**
   * Set to `true` to disable the button
   * @default false
   */
  disabled?: boolean;

  /**
   * Set the `href` to use an anchor link.
   * @default undefined
   */
  href?: string;

  /**
   * Specify the tabindex
   * @default "0"
   */
  tabindex?: number | string | undefined;

  /**
   * Specify the `type` attribute for the button element
   * @default "button"
   */
  type?: string;

  /**
   * Obtain a reference to the HTML element.
   * @default null
   */
  ref?: null | HTMLAnchorElement | HTMLButtonElement;

  /**
   * Set to `true` to render the icon-only tooltip in a portal,
   * preventing it from being clipped by `overflow: hidden` containers
   * and enabling auto-flipping when the preferred direction lacks space.
   * By default, the tooltip is portalled when inside a `Modal`.
   * @default undefined
   */
  portalTooltip?: boolean | undefined;

  /** Compose a `BadgeIndicator` overlaid on an icon-only button. Size is set to `lg` automatically. */
  badge?: (this: void) => void;

  children?: (this: void, ...args: [{
        props: {
          role: "button";
          type?: string;
          tabindex: any;
          disabled: boolean;
          href?: string;
          class: string;
          [key: string]: any;
        }
      }]) => void;

  [key: `data-${string}`]: unknown;
};

export type ButtonProps<Icon = any> = Omit<$RestProps, keyof ($Props<Icon> & ButtonSkeletonProps)> & $Props<Icon> & ButtonSkeletonProps;

export default class Button<Icon = any> extends SvelteComponentTyped<
  ButtonProps<Icon>,
  {
    blur: WindowEventMap["blur"];
    click: WindowEventMap["click"];
    focus: WindowEventMap["focus"];
    mousedown: WindowEventMap["mousedown"];
    mouseenter: WindowEventMap["mouseenter"];
    mouseleave: WindowEventMap["mouseleave"];
    mouseover: WindowEventMap["mouseover"];
  },
  {
    default: {
      props: {
        role: "button";
        type?: string;
        tabindex: any;
        disabled: boolean;
        href?: string;
        class: string;
        [key: string]: any;
      }
    };
    /** Compose a `BadgeIndicator` overlaid on an icon-only button. Size is set to `lg` automatically. */
    badge: Record<string, never>;
    icon: { style: undefined | string };
  }
> {}