@atlaskit/button
Version:
A button triggers an event or action. They let users know what will happen next.
120 lines (119 loc) • 6.31 kB
TypeScript
import type React from 'react';
import { type UIAnalyticsEvent } from '@atlaskit/analytics-next';
import { type IconProps, type NewIconProps } from '@atlaskit/icon/types';
export type ButtonAppearance = 'default' | 'danger' | 'primary' | 'subtle' | 'warning' | 'discovery';
export type LinkButtonAppearance = 'default' | 'danger' | 'primary' | 'subtle' | 'warning' | 'discovery';
export type IconButtonAppearance = 'default' | 'primary' | 'discovery' | 'subtle';
export type Appearance = ButtonAppearance | LinkButtonAppearance | IconButtonAppearance;
export type ButtonSpacing = 'compact' | 'default';
export type IconButtonSpacing = 'compact' | 'default';
export type Spacing = ButtonSpacing | IconButtonSpacing;
export type IconProp = React.ComponentType<Omit<IconProps, 'size'> | Omit<NewIconProps, 'spacing' | 'size'>>;
export type IconSize = 'small' | 'large' | 'xlarge';
type Combine<First, Second> = Omit<First, keyof Second> & Second;
export type CommonBaseProps = {
/**
* Set the button to autofocus on mount.
*/
autoFocus?: boolean;
/**
* Disable the button to prevent user interaction.
*/
isDisabled?: boolean;
/**
* Indicates that the button is selected.
*/
isSelected?: boolean;
/**
* A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests.
*/
testId?: string;
/**
* Additional information to be included in the `context` of Atlaskit analytics events that come from button. See [the pressable or anchor primitive code examples](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) for more information.
*/
analyticsContext?: Record<string, any>;
/**
* An optional name used to identify the button to interaction content listeners. By default, button fires React UFO (Unified Frontend Observability) press interactions for available listeners. This helps Atlassian measure performance and reliability. See [the pressable or anchor primitive code examples](https://atlassian.design/components/primitives/anchor/examples#react-ufo-press-interactions) for more information.
*/
interactionName?: string;
};
export type CommonButtonProps<TagName extends HTMLElement = HTMLButtonElement> = CommonBaseProps & {
/**
* Handler called on blur.
*/
onBlur?: React.FocusEventHandler<TagName>;
/**
* Handler called on focus.
*/
onFocus?: React.FocusEventHandler<TagName>;
/**
* Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See the pressable or anchor primitive code examples for information on [firing Atlaskit analytics events](https://atlassian.design/components/primitives/pressable/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/pressable/examples#gasv3-analytics).
*/
onClick?: (e: React.MouseEvent<TagName, MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void;
};
export type CommonAnchorProps<RouterLinkConfig extends Record<string, any> = never> = CommonBaseProps & {
/**
* Handler called on blur.
*/
onBlur?: React.FocusEventHandler<HTMLAnchorElement>;
/**
* Handler called on focus.
*/
onFocus?: React.FocusEventHandler<HTMLAnchorElement>;
/**
* Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See the pressable or anchor primitive code examples for information on [firing Atlaskit analytics events](https://atlassian.design/components/primitives/pressable/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/pressable/examples#gasv3-analytics).
*/
onClick?: (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void;
/**
* URL to navigate to.
*/
href?: string | RouterLinkConfig;
};
type SupportedElementAttributes = React.ButtonHTMLAttributes<HTMLButtonElement> | React.AnchorHTMLAttributes<HTMLAnchorElement>;
type AdditionalHTMLElementPropsExtender<Props extends SupportedElementAttributes> = Combine<Omit<Props, 'className' | 'style' | 'disabled'>, {
'data-testid'?: never;
}>;
/**
* Common additional props for button `<button>` variants
*/
export type AdditionalButtonVariantProps = {
/**
* The button style variation.
*/
appearance?: ButtonAppearance;
/**
* Conditionally show a spinner over the top of a button
*/
isLoading?: boolean;
};
/**
* Combines common button props with additional HTML attributes
*/
type CombinedButtonProps<TagName extends HTMLElement, HTMLAttributes extends SupportedElementAttributes> = Combine<HTMLAttributes, CommonButtonProps<TagName>>;
/**
* Common props for Button `<button>` variants
*/
export type CommonButtonVariantProps = AdditionalButtonVariantProps & CombinedButtonProps<HTMLButtonElement, AdditionalHTMLElementPropsExtender<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'>>>;
/**
* Common additional props for Link `<a>` Button variants, including icon and default buttons
*/
type AdditionalCommonLinkVariantProps<RouterLinkConfig extends Record<string, any> = never> = {
/**
* Provides a URL for link buttons. When using an AppProvider with a configured router link component, a `RouterLinkConfig` object type can be provided for advanced usage. See the [Link Button routing example](/components/button/examples#routing) for more details.
*/
href: string | RouterLinkConfig;
};
/**
* Additional props for default Link `<a>` Button variants
*/
export type AdditionalDefaultLinkVariantProps = {
/**
* The button style variation.
*/
appearance?: LinkButtonAppearance;
};
/**
* Common props for Link `<a>` Button variants
*/
export type CommonLinkVariantProps<RouterLinkConfig extends Record<string, any> = never> = AdditionalCommonLinkVariantProps<RouterLinkConfig> & CombinedButtonProps<HTMLAnchorElement, AdditionalHTMLElementPropsExtender<Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'children'>>>;
export {};