# Atlassian Design System Components > A comprehensive collection of React components that follow Atlassian's design system principles. > These components are built on top of design tokens and primitives to ensure consistent, > accessible, and responsive user interfaces across Atlassian apps. ## @atlaskit/avatar-group Package ### AvatarGroup component A component for displaying multiple avatars in a group with overlap and overflow handling. - **Keywords:** avatar, group, multiple, users, team, overlap, facepile - **Categories:** data-display - **Status:** general-availability #### Example ```tsx import AvatarGroup from '@atlaskit/avatar-group/avatar-group'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `"grid" \| "stack" \| undefined` | Indicates the layout of the avatar group. Avatars will either be overlapped in a stack, or laid out in an even grid formation. Defaults to "stack". | | `avatar` | `AvatarComponent \| React.ElementType \| undefined` | Component used to render each avatar. | | `borderColor` | `string \| undefined` | Typically the background color that the avatar is presented on. Accepts any color argument that the CSS border-color property accepts. | | `boundariesElement` | `"viewport" \| "window" \| "scrollParent" \| undefined` | Element the overflow popup should be attached to. Defaults to "viewport". | | `data` | `(AvatarPropTypes & { name: string; key?: string \| number \| undefined; })[]` | An array of avatar prop data, that are spread onto each `avatar` component. For further usage information on AvatarPropTypes, the supported props for `avatar`, refer to [Avatar's prop documentation](https://atlassian.design/components/avatar/code). (required) | | `isTooltipDisabled` | `boolean \| undefined` | Disables tooltips. | | `label` | `string \| undefined` | Text to be used as aria-label for the list of avatars. Screen reader announcement with default label, which is `avatar group`, is `list, avatar group, X items`. The label should describe the `AvatarGroup`'s entities, for instance: - `label="team members"`, screen reader announcement would be `list team members, X items` - `label="reviewers"` screen reader announcement would be `list reviewers, X items` When there are several AvatarGroups on the page you should use a unique label to let users distinguish different lists. | | `maxCount` | `number \| undefined` | The maximum number of avatars allowed in the list. Defaults to 5 when displayed as a stack, and 11 when displayed as a grid. | | `moreIndicatorLabel` | `string \| undefined` | Text to be used as aria-label for the more indicator. If provided, this will be used exactly as-is for the aria-label. If not provided, but an `aria-label` is provided via `showMoreButtonProps`, that will be used instead. If neither is provided, the aria-label will default to "N more people" where N is the number of people that are not visible (e.g. "5 more people"). | | `onAvatarClick` | `onAvatarClickHandler \| undefined` | Handle the click event on the avatar item. Note that if an onClick prop is provided as part of avatar data, it will take precedence over onAvatarClick. | | `onMoreClick` | `React.MouseEventHandler \| undefined` | Take control of the click event on the more indicator. This will cancel the default dropdown behavior. | | `overrides` | `AvatarGroupOverrides \| undefined` | Custom overrides for the composed components. | | `shouldPopupRenderToParent` | `boolean \| undefined` | Determines whether the 'show more' popup has `shouldRenderToParent` applied. | | `showMoreButtonProps` | `Partial> \| undefined` | Provide additional props to the MoreButton. Example use cases: altering tab order by providing tabIndex; adding onClick behaviour without losing the default dropdown | | `size` | `AvatarGroupSize \| undefined` | Defines the size of the avatar. Defaults to "medium". Note: The "xxsmall" (16px), legacy "xsmall", and "UNSAFE_xsmall" (20px) sizes that exist on Avatar are not supported here because elements such as the more indicator cannot be displayed in an accessible manner at those sizes. | | `tooltipPosition` | `"top" \| "bottom" \| undefined` | Where the tooltip should appear relative to its target. Defaults to tooltip position "bottom". | #### Usage Guidelines - Use for displaying multiple users or team members - Consider overflow behavior for large groups - Use appropriate sizing for context - Provide clear user identification #### Content Guidelines - Use meaningful names for users - Consider group context and purpose - Provide clear overflow indicators - Use consistent naming patterns #### Accessibility Guidelines - Provide clear labels for avatar groups - Use appropriate overflow handling - Ensure keyboard navigation support - Provide clear user identification ## @atlaskit/avatar Package ### Avatar component A component for displaying user avatars with support for images, initials, and status indicators. - **Keywords:** avatar, user, profile, image, picture, photo, presence, status, representation - **Categories:** images - **Status:** general-availability #### Example ```tsx import Avatar from '@atlaskit/avatar/avatar'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `AppearanceType \| undefined` | Indicates the shape of the avatar. Most avatars are circular, but square avatars can be used for 'container' objects. | | `aria-controls` | `string \| undefined` | Identifies the popup element that the trigger controls. Should match the `id` of the popup content for screen readers to understand the relationship. | | `aria-expanded` | `boolean \| undefined` | Announces to assistive technology whether the popup is currently open or closed. | | `aria-haspopup` | `boolean \| "grid" \| "dialog" \| "menu" \| "listbox" \| "tree" \| undefined` | Informs assistive technology that this element triggers a popup. With `platform-dst-top-layer`, it is not set when the popup has no `role`. | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType> \| undefined` | Replace the wrapping element. This accepts the name of a html tag which will be used to wrap the element. | | `borderColor` | `string \| undefined` | Used to override the default border color around the avatar body. Accepts any color argument that the border-color CSS property accepts. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Supply a custom avatar component instead of the default. | | `href` | `string \| undefined` | Provides a url for avatars being used as a link. | | `imgLoading` | `"lazy" \| "eager" \| undefined` | Defines the loading behaviour of the avatar image. Default value is eager. | | `isDisabled` | `boolean \| undefined` | Change the style to indicate the avatar is disabled. | | `label` | `string \| undefined` | Used to provide custom content to screen readers. Status or presence is not added to the label by default if it passed as nodes. If status or presence is passed as a string, the default content format is "John Smith (online)". | | `name` | `string \| undefined` | Provides alt text for the avatar image. | | `onClick` | `AvatarClickEventHandler \| undefined` | Handler to be called on click. | | `presence` | `(string & {}) \| Presence \| Omit \| null \| undefined` | Indicates a user's online status by showing a small icon on the avatar. Refer to presence values on the presence component. Alternatively accepts any React element. For best results, it is recommended to use square content with height and width of 100%. | | `size` | `SizeType \| undefined` | Defines the size of the avatar. Default value is `medium`. Available sizes (in pixels): `xxsmall` (16), `small` (24), `medium` (32), `large` (40), `xlarge` (96), `xxlarge` (128). The `xsmall` size is deprecated. Use `xxsmall` for 16px avatars. The `UNSAFE_xsmall` (20px) size is an unsafe, transitional value and is intentionally not documented for general use — see `SizeType`. This can also be controlled by the `size` property of the `AvatarContext` export from this package. If no prop is given when the `size` is set via this context, the context's value will be used. | | `src` | `string \| undefined` | A url to load an image from (this can also be a base64 encoded image). | | `stackIndex` | `number \| undefined` | The index of where this avatar is in the group `stack`. | | `status` | `(string & {}) \| Omit \| Status \| null \| undefined` | Indicates contextual information by showing a small icon on the avatar. Refer to status values on the Status component. | | `tabIndex` | `number \| undefined` | Assign specific tabIndex order to the underlying node. | | `target` | `"_blank" \| "_self" \| "_top" \| "_parent" \| undefined` | Pass target down to the anchor, if href is provided. | #### Usage Guidelines - Use for user or entity (repo, space). Circle = person; hexagon = agent/AI; square = project/repo/space - Use presence for availability; status for approval/permission states - Use consistent sizing within the same context - Use `xxsmall` for new 16px avatars. In the current major, legacy `xsmall` is also 16px and should migrate to `xxsmall` with the Avatar codemod; `xsmall` will become 20px in a future major - Do not use 16px or 20px sizes with AvatarGroup - Place avatars in logical groupings (e.g., team members) - Use presence indicators sparingly for real-time status only - Provide fallback initials when images fail to load - Always provide meaningful names for accessibility - Use the `name` prop to include alternative text for screen readers - For decorative images, remove the `name` prop or leave it empty so it will be ignored by assistive technologies - Don't use a tooltip with an avatar when it's non-interactive or disabled. The tooltip won't work for keyboard users and screen readers #### Content Guidelines - Use full names when possible for better recognition - For companies/projects, use descriptive names - Avoid generic terms like 'User' or 'Admin' - Use consistent naming conventions across your app - Keep names concise but meaningful ### AvatarContent component A wrapper component for custom avatar content that provides consistent styling and behavior. - **Keywords:** avatar, content, custom, children, wrapper - **Categories:** images - **Status:** general-availability #### Example ```tsx /** * @jsxRuntime classic * @jsx jsx */ import Avatar from '@atlaskit/avatar/avatar'; import { AvatarContent } from '@atlaskit/avatar/avatar-content'; import { css, jsx } from '@atlaskit/css'; import PeopleGroupIcon from '@atlaskit/icon/core/people-group'; import { token } from '@atlaskit/tokens'; const styles = { iconContainer: css({ display: 'grid', height: '100%', backgroundColor: token('elevation.surface'), placeItems: 'center', }), }; function AvatarContentExample(): JSX.Element { return (
); } export default AvatarContentExample; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | | #### Usage Guidelines - Use for custom avatar content that needs consistent styling - Wrap custom content to maintain avatar behavior - Ensure custom content follows avatar design principles - Use when standard avatar props don't meet your needs #### Content Guidelines - Ensure custom content is appropriate for avatar context - Maintain consistent visual hierarchy - Keep custom content simple and clear ### AvatarItem component A component that combines an avatar with text content for displaying user information in lists. AvatarItem combines an avatar with primary and secondary text to create a rich user representation in lists and menus. It supports both interactive (clickable) and non-interactive modes, making it perfect for user lists, team members, or any context where you need to display user information with actions. - **Keywords:** avatar, item, list, user, profile, interactive - **Categories:** images - **Status:** general-availability #### Example ```tsx import Avatar from '@atlaskit/avatar/avatar'; import AvatarItem from '@atlaskit/avatar/avatar-item'; const Example = (): React.JSX.Element => ( } primaryText="Bob Wilson" secondaryText="bob.wilson@company.com" href="/user/bob-wilson" /> ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `avatar` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Slot to place an avatar element. Use @atlaskit/avatar. (required) | | `backgroundColor` | `string \| undefined` | Change background color. | | `href` | `string \| undefined` | URL for avatars being used as a link. | | `isDisabled` | `boolean \| undefined` | Disable the item from being interactive. | | `isTruncationDisabled` | `boolean \| undefined` | By default, overflowing text is truncated if it exceeds the container width. Use this prop to disable this. | | `label` | `string \| undefined` | Used to provide better content to screen readers when using presence/status. Rather than a screen reader speaking "online, approved, John Smith", passing in an label allows a custom message like "John Smith (approved and online)". | | `onClick` | `AvatarClickEventHandler \| undefined` | Handler to be called on click. | | `primaryText` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | PrimaryText text. | | `secondaryText` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | SecondaryText text. | | `target` | `"_blank" \| "_self" \| "_top" \| "_parent" \| undefined` | Pass target down to the anchor, if href is provided. | #### Usage Guidelines - Use for displaying user information in lists and menus - Choose between interactive and display-only based on context - Provide clear primary and secondary text hierarchy - Use consistent spacing and alignment within lists - Consider the interaction pattern before implementation - Use AvatarItem when you need to show user information with additional context like names, emails, or status information - Provide clear primary and secondary text - Use meaningful labels for accessibility - Consider the interaction pattern (clickable vs display-only) based on your use case #### Content Guidelines - Use clear, descriptive primary text (usually names) - Provide relevant secondary text (emails, roles, etc.) - Keep text concise but informative - Use consistent formatting across similar items - Avoid redundant information between primary and secondary text ### Presence component A standalone component for displaying user presence indicators. Presence indicators show the current availability status of users. They help other users understand when someone is available for communication and are useful in collaborative applications where knowing someone's availability is important for workflow. - **Keywords:** presence, status, online, offline, busy, focus, indicator - **Categories:** status - **Status:** general-availability #### Example ```tsx import Presence from '@atlaskit/avatar/presence'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `borderColor` | `string \| undefined` | Used to override the default border color of the presence indicator. Accepts any color argument that the border-color CSS property accepts. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Content to use as a custom presence indicator (usually not required if consuming Presence separate to Avatar). | | `presence` | `Presence \| undefined` | The type of presence indicator to show. | #### Usage Guidelines - Prefer using `` instead of `` - Use sparingly for real-time status only - Don't overuse as they can create visual clutter - Show presence only when relevant to user workflow - Use consistent presence states across the application - Consider the context and user needs before showing presence - Use presence indicators sparingly for real-time status - Don't overuse them as they can create visual clutter - Only show presence when it's relevant to the user's workflow #### Content Guidelines - Use clear, universally understood presence states - Be consistent with presence terminology - Provide clear visual distinction between states - Avoid ambiguous or unclear presence indicators ### Skeleton component A skeleton loading component for avatars that shows a placeholder while content is loading. Skeleton components provide visual feedback during loading states, helping users understand that content is being fetched. Skeleton components should match the size and shape of the actual content they're replacing to prevent layout shifts. - **Keywords:** skeleton, loading, placeholder, shimmer, avatar - **Categories:** loading - **Status:** general-availability #### Example ```tsx import Skeleton from '@atlaskit/avatar/skeleton'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `AppearanceType \| undefined` | Indicates the shape of the avatar skeleton. Most avatars are circular, but square avatars can be used for container objects. | | `color` | `string \| undefined` | Color of the skeleton. By default, it will inherit the current text color. | | `size` | `SizeType \| undefined` | Defines the size of the avatar skeleton. | | `weight` | `"strong" \| "normal" \| undefined` | Defines the opacity of the avatar skeleton. Use `weight="normal"` for the default opacity, or `weight="strong"` for a bolder opacity. | #### Usage Guidelines - Use during loading states to maintain layout stability - Match the size and shape of the actual avatar content - Prevent layout shifts by maintaining consistent dimensions - Use for short loading periods (under 3 seconds) - Consider using spinners for longer loading times - Use skeleton avatars when user data is loading to maintain layout stability and provide visual feedback - Match the size and shape of the actual avatar content to prevent layout shifts #### Content Guidelines - Keep skeleton content minimal and non-distracting - Use consistent skeleton patterns across similar components - Avoid overly detailed skeleton content - Ensure skeleton content is clearly distinguishable from real content ### Status component A standalone component for displaying status indicators. Status indicators show the approval or permission state of users or entities. They help communicate important state information at a glance and are useful in workflow applications where approval states or permissions are important for user understanding. - **Keywords:** status, approved, declined, locked, indicator, permission - **Categories:** status - **Status:** general-availability #### Example ```tsx import Status from '@atlaskit/avatar/status'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `borderColor` | `string \| undefined` | Override the default border color of the status indicator. This accepts any color argument that the CSS property `border-color` accepts. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Content to use as a custom status indicator. Not needed if consuming `Status` separate to `Avatar`. | | `status` | `Status \| undefined` | The type of status indicator to show. | #### Usage Guidelines - Prefer using `` instead of `` - Use for approval states, permission levels, or important state information - Make sure the status is relevant and helpful to user workflow - Use consistent status states across the application - Consider the context and user needs before showing status - Don't overuse status indicators to avoid visual clutter - Use status indicators to show approval states, permission levels, or other important state information that affects how users should interact with the entity - Make sure the status is relevant and helpful to the user's workflow #### Content Guidelines - Use clear, universally understood status states - Be consistent with status terminology - Provide clear visual distinction between states - Avoid ambiguous or unclear status indicators ## @atlaskit/badge Package ### Badge component A badge is a visual indicator for numeric values such as tallies and scores, providing quick visual feedback. - **Keywords:** badge, indicator, numeric, tally, score, count, status, bold, appearance, notification - **Categories:** status-indicators - **Status:** general-availability #### Example ```tsx import Badge from '@atlaskit/badge/badge'; const Examples = (): React.JSX.Element => ( <> 5 150 ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `"warning" \| "added" \| "default" \| "important" \| "primary" \| "primaryInverted" \| "removed" \| "discovery" \| "danger" \| "neutral" \| "success" \| "information" \| "inverse" \| "informationBold" \| ... 4 more ... \| undefined` | Affects the visual style of the badge. | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | The value displayed within the badge. A `ReactNode` can be provided for custom-formatted numbers, however, badge should only be used in cases where you want to represent a number. Use a [lozenge](/packages/design-system/lozenge) for non-numeric information. | | `max` | `number \| false \| undefined` | The maximum value to display. Defaults to `99`. If the value is 100, and max is 50, "50+" will be displayed. This value should be greater than 0. If set to `false` the original value will be displayed regardless of whether it is larger than the default maximum value. | #### Usage Guidelines - Use for displaying counts, scores, or status indicators for a single item or label - Use with one item/label only to avoid ambiguity - Keep badge content concise and meaningful - Use appropriate appearance variants for different contexts. Default semantic appearances: neutral, success, danger, warning, information, discovery, and inverse. - Bold semantic appearances (successBold, dangerBold, warningBold, informationBold, discoveryBold) give higher visual prominence. - Only use bold semantic badges for elements of high importance, such as notification counts. Avoid bold badges for elements that are secondary to other labels (e.g. alongside a lozenge). - Position badges near relevant content - Consider maximum value display limits - Add a tooltip when the badge has an icon or needs extra context. - Use Lozenge for non-numeric status; use Tag for labels #### Content Guidelines - Use clear, concise numeric or text values - Ensure values are meaningful to users - Use consistent formatting across similar badges - Consider localization for number formatting (locale-aware numbers) #### Accessibility Guidelines - Ensure badge content is announced by screen readers - Do not rely on color alone for positive/negative meaning - Use appropriate color contrast for text readability - Provide meaningful context for numeric values - Consider alternative text for non-numeric badges ## @atlaskit/banner Package ### Banner component A banner displays a prominent message at the top of the screen to communicate important information to users. - **Keywords:** banner, message, notification, alert, prominent, top, screen - **Categories:** messaging - **Status:** general-availability #### Example ```tsx import Banner from '@atlaskit/banner/banner'; import { cssMap } from '@atlaskit/css'; import WarningIcon from '@atlaskit/icon/core/status-warning'; import Box from '@atlaskit/primitives/box'; import { Flex } from '@atlaskit/primitives/compiled/flex'; import { token } from '@atlaskit/tokens'; const iconSpacingStyles = cssMap({ space050: { paddingBlock: token('space.050'), paddingInline: token('space.050'), }, }); export default (): React.JSX.Element => ( } testId="basicTestId" > Your license is about to expire. Please renew your license within the next week. ); ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `Appearance \| undefined` | Visual style to be used for the banner | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Content to be shown next to the icon. Typically text content but can contain links. | | `icon` | `ReactElement> \| undefined` | Icon to be shown left of the main content. Typically an Atlaskit [@atlaskit/icon](packages/design-system/icon) | #### Usage Guidelines - Use only for critical messaging: loss of data/functionality or important site-wide information - Show one banner at a time and push content down - Place at the top of the screen for maximum visibility - Keep messaging concise and actionable - Consider dismissibility for non-critical messages - Use Flag for confirmations or minimal interaction; use Inline message when action is required #### Content Guidelines - Use "we" not "you" in error messages - Write clear, concise, scannable messages - Include follow-up actions where relevant - Use action-oriented language when appropriate - Ensure messages are relevant to the current context #### Accessibility Guidelines - Do not rely on color alone for severity; provide accessible label for warning/error icons - Alert role is a live region and very noisy—use only when the message is very important - Keep content concise to avoid truncation (truncation is not accessible) - Use appropriate color contrast for text readability - Provide clear, actionable messaging - Consider keyboard navigation for interactive banners ## @atlaskit/blanket Package ### Blanket component A component for creating overlay backgrounds behind modals and other layered content. - **Keywords:** blanket, overlay, backdrop, modal, layer - **Categories:** overlay - **Status:** general-availability #### Example ```tsx import Blanket from '@atlaskit/blanket/blanket'; const Examples = (): React.JSX.Element => ( <> console.log('Blanket clicked')} /> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | The children to be rendered within the blanket. | | `isTinted` | `boolean \| undefined` | Sets whether the blanket has a tinted background color. | | `onBlanketClicked` | `((event: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Handler function to be called when the blanket is clicked. | | `shouldAllowClickThrough` | `boolean \| undefined` | Whether mouse events can pass through the blanket. If `true`, `onBlanketClicked` will not be called. | #### Usage Guidelines - Use behind modals and overlays - Consider click-to-dismiss behavior - Use appropriate tinting for context - Ensure proper z-index layering #### Content Guidelines - Use consistently across similar overlay contexts - Consider visual hierarchy with overlays - Ensure appropriate contrast with content #### Accessibility Guidelines - Ensure blanket doesn't interfere with focus management - Provide appropriate click handling for dismissal - Consider screen reader experience with overlays ## @atlaskit/breadcrumbs Package ### Breadcrumbs component A navigation component showing the current page hierarchy. - **Keywords:** breadcrumbs, navigation, hierarchy, path, location - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import Breadcrumbs from '@atlaskit/breadcrumbs/breadcrumbs'; import { BreadcrumbsCurrentItem } from '@atlaskit/breadcrumbs/breadcrumbs-current-item'; import { BreadcrumbsItem } from '@atlaskit/breadcrumbs/breadcrumbs-item'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | The items to be included inside the Breadcrumbs wrapper. | | `ellipsisLabel` | `string \| undefined` | Text to be used as an accessible label for the ellipsis button that reveals collapsed breadcrumb items in a popup. | | `label` | `string \| undefined` | Text to be used as label of navigation region that wraps the breadcrumbs. | | `size` | `"small" \| "medium" \| undefined` | The size variant of the breadcrumbs. Use `'small'` for a compact presentation with smaller text (`font.body.small`) and smaller icons. | #### Usage Guidelines - Use for orientation; supplement main nav, do not replace it - Hierarchy from top to current; each item is a link - Place top left, above page title; use when user lands from external or on large/hierarchical sites - Do not overwhelm; in-app avoid topmost level unless sidebar is collapsed #### Content Guidelines - Use page or section titles for items - Keep labels concise but meaningful - Use consistent naming conventions #### Accessibility Guidelines - Ensure separator contrast; separators are not announced to screen readers - Collapsed state = single item (e.g. "Show more breadcrumbs") - Use isNavigation={false} when breadcrumbs are not main nav (e.g. search results) to reduce assistive tech noise - Provide clear navigation labels - Use appropriate ARIA landmarks - Ensure keyboard navigation support - Provide clear path context ### BreadcrumbsItem component An individual breadcrumb item within the breadcrumb trail. Each item can be a link (with href) or plain text for the current page. - **Keywords:** breadcrumbs, item, navigation, link, hierarchy - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import Breadcrumbs from '@atlaskit/breadcrumbs/breadcrumbs'; import { BreadcrumbsCurrentItem } from '@atlaskit/breadcrumbs/breadcrumbs-current-item'; import { BreadcrumbsItem } from '@atlaskit/breadcrumbs/breadcrumbs-item'; const BreadcrumbsDefaultExample = (): React.JSX.Element => { return ( ); }; export default BreadcrumbsDefaultExample; ``` #### Props | Prop | Type | Description | |-|-|-| | `_overflowRef` | `((el: HTMLLIElement \| null) => void) \| undefined` | | | `aria-current` | `boolean \| "page" \| undefined` | | | `aria-label` | `string \| undefined` | Accessible label applied to the interactive breadcrumb control. | | `aria-labelledby` | `string \| undefined` | Accessible labelling relationship applied to the interactive breadcrumb control. | | `elemBefore` | `ReactChild \| undefined` | An element to display before the breadcrumb. | | `href` | `string \| undefined` | The url or path which the breadcrumb should act as a link to. | | `onClick` | `((event: MouseEvent) => void) \| undefined` | Handler to be called on click. * | | `onTooltipShown` | `(() => void) \| undefined` | A function to be called when a truncated breadcrumb item's tooltip is shown. | | `target` | `"" \| "_blank" \| "_self" \| "_top" \| "_parent" \| undefined` | | | `text` | `string` | The text to appear within the breadcrumb as a link. (required) | | `title` | `string \| undefined` | Advisory text applied to the interactive breadcrumb control. | | `truncationWidth` | `number \| undefined` | The maximum width in pixels that an item can have before it is truncated. If this is not set, truncation will only occur when it cannot fit alone on a line. If there is no truncationWidth, tooltips are not provided on truncation. | #### Usage Guidelines - Use within Breadcrumbs wrapper to define each step in the hierarchy - Use href for navigable items; omit href for the current page - Support iconBefore and iconAfter for contextual indicators - Use truncationWidth when items may be long to prevent overflow #### Content Guidelines - Use page or section titles for the text prop - Keep labels concise but meaningful - Use consistent naming conventions across the breadcrumb trail #### Accessibility Guidelines - Provide meaningful text for screen readers - Ensure link targets are descriptive ## @atlaskit/button Package ### ButtonGroup component A component for grouping related buttons together with consistent spacing and alignment. - **Keywords:** button, group, container, layout, spacing - **Categories:** form - **Status:** general-availability #### Example ```tsx import ButtonGroup from '@atlaskit/button/button-group'; import Button from '@atlaskit/button/default/button'; const _default_1: React.JSX.Element[] = [ , ]; export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The buttons to render inside the button group. | | `label` | `string \| undefined` | Refers to an `aria-label` attribute. Sets an accessible name for the button group wrapper to announce it to users of assistive technology. Usage of either this, or the `titleId` attribute is strongly recommended. | | `titleId` | `string \| undefined` | ID referenced by the button group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group-button title element. Usage of either this, or the `label` attribute is strongly recommended. | #### Usage Guidelines - Use for related actions that belong together - Group buttons that perform similar or complementary actions - Maintain consistent spacing and alignment - Consider the visual hierarchy within the group - Don't group unrelated actions together - Use when you have multiple related actions that should be visually grouped - Provides consistent spacing and alignment between buttons #### Content Guidelines - Ensure button labels are consistent in tone and style - Use parallel structure for related actions - Keep labels concise but descriptive - Consider the order of actions within the group ### Button component A versatile button component with multiple appearances and states for triggering actions. A button triggers an event or action. They let users know what will happen next. - **Keywords:** button, action, click, submit, form, interactive, cta - **Categories:** form - **Status:** general-availability #### Example ```tsx import Button from '@atlaskit/button/default/button'; export default function ButtonDisabledExample(): React.JSX.Element { return ( ); } ``` #### Example ```tsx import Button from '@atlaskit/button/default/button'; export default function ButtonDangerExample(): React.JSX.Element { return ; } ``` #### Example ```tsx import Button from '@atlaskit/button/default/button'; import StarIcon from '@atlaskit/icon/core/star-starred'; export default function ButtonIconAfterExample(): React.JSX.Element { return ( ); } ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `ButtonAppearance \| undefined` | The button style variation. | | `autoFocus` | `boolean \| undefined` | Set the button to autofocus on mount. | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Text content to be rendered in the button. (required) | | `iconAfter` | `IconProp \| undefined` | Places an icon within the button, after the button's text. | | `iconBefore` | `IconProp \| undefined` | Places an icon within the button, before the button's text. | | `isDisabled` | `boolean \| undefined` | Disable the button to prevent user interaction. | | `isLoading` | `boolean \| undefined` | Conditionally show a spinner over the top of a button | | `isSelected` | `boolean \| undefined` | Indicates that the button is selected. | | `onBlur` | `FocusEventHandler \| undefined` | Handler called on blur. | | `onClick` | `((e: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | 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). | | `onFocus` | `FocusEventHandler \| undefined` | Handler called on focus. | | `shouldFitContainer` | `boolean \| undefined` | Option to fit button width to its parent width. | | `spacing` | `ButtonSpacing \| undefined` | Controls the amount of padding in the button. | #### Usage Guidelines - Use primary buttons for the main action on a page - Limit to one primary button per section - Use compact size for tight spaces - Use subtle buttons for secondary actions - Use danger buttons sparingly for destructive actions - Group related buttons together with ButtonGroup - Use buttons for actions; use links for navigation (different semantics and assistive tech behavior) #### Content Guidelines - Use action verbs that describe the interaction - Keep text concise (1-3 words ideal) - Avoid generic terms like "Submit" or "Click here" - Use sentence case - Keep button labels consistent with surrounding UI (e.g. modal primary button should reflect modal intent) - Use buttons for actions, links for navigation - Only include one primary call to action (CTA) per area - Start with the verb and specify what's being acted on - Don't use punctuation in button labels #### Accessibility Guidelines - Always provide meaningful labels for screen readers - Provide loading state announcements for async actions ### IconButton component A button that displays only an icon with an optional tooltip. Perfect for toolbar actions, compact interfaces, and when space is limited. - **Keywords:** button, icon, action, click, interactive, toolbar - **Categories:** form - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import AddIcon from '@atlaskit/icon/core/add'; import DeleteIcon from '@atlaskit/icon/core/delete'; import InfoIcon from '@atlaskit/icon/core/status-information'; const _default_1: React.JSX.Element[] = [ , , , ]; export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `"default" \| "primary" \| "discovery" \| "rovo" \| "subtle" \| undefined` | The button style variation. The button style variation. | | `autoFocus` | `boolean \| undefined` | Set the button to autofocus on mount. | | `icon` | `ComponentClass<(Omit \| Omit) & { motionOvershoot?: string \| undefined; }, any> \| FunctionComponent<...>` | Places an icon within the button. (required) | | `isDisabled` | `boolean \| undefined` | Disable the button to prevent user interaction. | | `isLoading` | `boolean \| undefined` | Conditionally show a spinner over the top of a button | | `isSelected` | `boolean \| undefined` | Indicates that the button is selected. | | `isTooltipDisabled` | `boolean \| undefined` | Prevents a tooltip with the label text from showing. Use sparingly, as most icon-only buttons benefit from a tooltip or some other text clarifying the action. | | `label` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Provide an accessible label, often used by screen readers. (required) | | `onBlur` | `FocusEventHandler \| undefined` | Handler called on blur. | | `onClick` | `((e: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | 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). | | `onFocus` | `FocusEventHandler \| undefined` | Handler called on focus. | | `shape` | `"circle" \| "default" \| undefined` | Set the shape of the icon, defaults to square with rounded corners. | | `spacing` | `IconButtonSpacing \| undefined` | Controls the amount of padding in the button. | | `tooltip` | `Partial> \| undefined` | Props passed down to the Tooltip component. | #### Usage Guidelines - Use for toolbar actions and compact interfaces - Choose icons that clearly represent their function - Group related icon buttons together - Use sparingly to avoid visual clutter - Consider using tooltips for additional context - Always provide a meaningful label for accessibility - The icon should clearly represent the action it performs #### Content Guidelines - Use clear, concise, descriptive labels - Use action verbs (e.g., "Edit item", "Delete comment") - Choose icons that are universally understood - Avoid using icons without labels in critical actions ### LinkIconButton component An icon-only button that helps people navigate to a common link or page location. - **Keywords:** button, icon, link, navigation, href, anchor - **Categories:** form - **Status:** general-availability #### Example ```tsx import LinkIconButton from '@atlaskit/button/icon/link'; import QuestionCircleIcon from '@atlaskit/icon/core/question-circle'; const LinkIconButtonDefaultExample = (): React.JSX.Element => { return ( ); }; export default LinkIconButtonDefaultExample; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `IconButtonAppearance \| undefined` | The button style variation. | | `autoFocus` | `boolean \| undefined` | Set the button to autofocus on mount. | | `href` | `(string \| RouterLinkConfig) & (string \| RouterLinkConfig \| undefined)` | 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. URL to navigate to. (required) | | `icon` | `React.ComponentClass<(Omit \| Omit) & { motionOvershoot?: string \| undefined; }, any> \| React.FunctionComponent<...>` | Places an icon within the button. (required) | | `isDisabled` | `boolean \| undefined` | Disable the button to prevent user interaction. | | `isSelected` | `boolean \| undefined` | Indicates that the button is selected. | | `isTooltipDisabled` | `boolean \| undefined` | Prevents a tooltip with the label text from showing. Use sparingly, as most icon-only buttons benefit from a tooltip or some other text clarifying the action. | | `label` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Provide an accessible label, often used by screen readers. (required) | | `newWindowLabel` | `string \| undefined` | Override the default text used to announce that the link opens in a new window. This should be localized when the product is displayed in a non-English locale. | | `onBlur` | `React.FocusEventHandler \| undefined` | Handler called on blur. Handler called on blur. | | `onClick` | `(((e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) & ((e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void)) \| undefined` | 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). 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). | | `onFocus` | `React.FocusEventHandler \| undefined` | Handler called on focus. Handler called on focus. | | `shape` | `"circle" \| "default" \| undefined` | Set the shape of the icon, defaults to square with rounded corners. | | `spacing` | `IconButtonSpacing \| undefined` | Controls the amount of padding in the button. | | `tooltip` | `Partial> \| undefined` | Props passed down to the Tooltip component. | #### Usage Guidelines - Use for navigation or other actions that change the page URL or location - Use an existing system icon with a clear, commonly understood meaning - Use a link button with a text label when the icon alone would be ambiguous #### Content Guidelines - Always provide a clear and specific label for tooltips and screen readers - Use sentence case for labels - Specify the object being acted on where possible, such as "Edit page" instead of "Edit" #### Accessibility Guidelines - Always provide a meaningful label; it is rendered as visually hidden content for assistive technologies - Avoid disabling buttons where possible ### LinkButton component A button that renders as an anchor tag for navigation. Combines the visual appearance of a button with the semantic behavior of a link. - **Keywords:** button, link, navigation, href, anchor - **Categories:** form - **Status:** general-availability #### Example ```tsx import LinkButton from '@atlaskit/button/link'; const _default_1: React.JSX.Element[] = [ External Link , // With a Router (requires `` setup at the root) About Page, ]; export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `LinkButtonAppearance \| undefined` | The button style variation. | | `autoFocus` | `boolean \| undefined` | Set the button to autofocus on mount. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Text content to be rendered in the button. (required) | | `href` | `string \| RouterLinkConfig` | 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. (required) | | `iconAfter` | `IconProp \| undefined` | Places an icon within the button, after the button's text. | | `iconBefore` | `IconProp \| undefined` | Places an icon within the button, before the button's text. | | `isDisabled` | `boolean \| undefined` | Disable the button to prevent user interaction. | | `isSelected` | `boolean \| undefined` | Indicates that the button is selected. | | `onBlur` | `React.FocusEventHandler \| undefined` | Handler called on blur. | | `onClick` | `((e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | 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). | | `onFocus` | `React.FocusEventHandler \| undefined` | Handler called on focus. | | `shouldFitContainer` | `boolean \| undefined` | Option to fit button width to its parent width. | | `spacing` | `ButtonSpacing \| undefined` | Controls the amount of padding in the button. | #### Usage Guidelines - Use for navigation actions that change the URL - Use for external links and internal navigation - Consider using regular buttons for actions that don't navigate - Provide clear visual indication of link behavior - Use consistent styling with other buttons when appropriate - Use for navigation actions that should look like buttons but behave like links - Perfect for external links, internal navigation, or any action that changes the URL #### Content Guidelines - Use clear, descriptive text that indicates the destination - Be specific about where the link will take the user - Use action-oriented language when appropriate - Avoid generic terms like 'Click here' or 'Learn more' ### SplitButton component A button that splits into a primary action and a dropdown menu. The main button performs the primary action, while the dropdown arrow reveals additional related actions. - **Keywords:** button, split, dropdown, menu, action, options - **Categories:** form - **Status:** general-availability #### Example ```tsx import Button from '@atlaskit/button/default/button'; import IconButton from '@atlaskit/button/icon/button'; import { SplitButton } from '@atlaskit/button/split-button/split-button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import ChevronDownIcon from '@atlaskit/icon/core/chevron-down'; const _default_1: React.JSX.Element = ( ( )} > Create new link Link existing item ); export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `SplitButtonAppearance \| undefined` | The style variation for child buttons. Will override any appearance set on a child button. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Only two children are allowed. First child is the primary action, second child is the secondary action. The assumption is that for both children trees there is a button reading the context. (required) | | `isDisabled` | `boolean \| undefined` | Whether all child buttons should be disabled. | | `spacing` | `SplitButtonSpacing \| undefined` | Controls the amount of padding in the child buttons. | #### Usage Guidelines - Always must have exactly two children: `Button` and `DropdownMenu` that are related to each other - Use `shouldRenderToParent` on `DropdownMenu` for proper positioning - Make the primary action the most common or important action - Limit dropdown items to avoid overwhelming users #### Content Guidelines - Use clear, action-oriented text for the primary button - Keep dropdown item labels concise and descriptive - Use consistent terminology across related actions #### Accessibility Guidelines - Provide descriptive labels for the IconButton trigger ## @atlaskit/calendar Package ### Calendar component A calendar component for date selection and display. This component is in Beta phase, meaning it's stable at version 1.0+ but may receive improvements based on customer feedback. - **Keywords:** calendar, date, picker, selection, month, year, beta - **Categories:** form - **Status:** general-availability #### Example ```tsx import Calendar from '@atlaskit/calendar/calendar'; const Examples = (): React.JSX.Element => ( <> console.log('Selected dates:', dates)} /> console.log('Multiple dates:', dates)} defaultMonth={3} defaultYear={2024} /> console.log('Constrained dates:', dates)} /> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `day` | `number \| undefined` | The number of the day currently focused. Places border around the date. Enter `0` to highlight no date. | | `defaultDay` | `number \| undefined` | Sets the default value for `day`. | | `defaultMonth` | `number \| undefined` | Sets the default value for `month`. | | `defaultPreviouslySelected` | `string[] \| undefined` | Sets the default value for `previouslySelected`. | | `defaultSelected` | `string[] \| undefined` | Sets the default value for `selected`. | | `defaultYear` | `number \| undefined` | Sets the default value for `year`. | | `disabled` | `string[] \| undefined` | Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are greyed out and not selectable. | | `disabledDateFilter` | `((date: string) => boolean) \| undefined` | A filter function that takes a date string in the format 'YYYY-MM-DD' and returns true if that date should be disabled. | | `headingLevel` | `HeadingLevel \| undefined` | The semantic heading level for the month and year title. Does not change its visual appearance. Overrides the surrounding `HeadingContextProvider` when provided. Otherwise, uses the heading context, falling back to level 2 when no context is available. | | `label` | `string \| undefined` | The accessible label for the calendar. | | `locale` | `string \| undefined` | BCP 47 language tag (e.g. `ja-JP`) that ensures dates are in the official format for the locale. | | `maxDate` | `string \| undefined` | The latest enabled date. All dates in the future after this date will be disabled. | | `minDate` | `string \| undefined` | The earliest enabled date. All dates in the past before this date will be disabled. | | `month` | `number \| undefined` | The number of the month (from 1 to 12) which the calendar should be on. | | `nextMonthLabel` | `string \| undefined` | The aria-label attribute associated with the next month arrow, to describe it to assistive technology. | | `onBlur` | `FocusEventHandler \| undefined` | Function which is called when the calendar is no longer focused. | | `onChange` | `((event: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Called when the calendar is navigated. This can be triggered by the keyboard, or by clicking the navigational buttons. The 'interface' property indicates the the direction the calendar was navigated whereas the 'iso' property is a string of the format YYYY-MM-DD. | | `onFocus` | `FocusEventHandler \| undefined` | Called when the calendar receives focus. This could be called from a mouse event on the container, or by tabbing into it. | | `onSelect` | `((event: SelectEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Function called when a day is clicked on. Calls with an object that has a day, month and year property as numbers, representing the date just clicked. It also has an 'iso' property, which is a string of the selected date in the format YYYY-MM-DD. | | `previouslySelected` | `string[] \| undefined` | Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are given a background color. | | `previousMonthLabel` | `string \| undefined` | The aria-label attribute associated with the previous month arrow, to describe it to assistive technology. | | `selected` | `string[] \| undefined` | Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are given a background color. | | `shouldSetFocusOnCurrentDay` | `boolean \| undefined` | This allows the calendar to automatically set the focus to the current day. The default is false. | | `tabIndex` | `TabIndex \| undefined` | Indicates if the calendar can be focused by keyboard or only programmatically. Defaults to "0". | | `today` | `string \| undefined` | Value of current day, as a string in the format 'YYYY-MM-DD'. | | `weekStartDay` | `WeekDay \| undefined` | Start day of the week for the calendar. The mapping between numbers and days of the week is as follows: - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday Defaults to the first day of the week for the given `locale`. | | `year` | `number \| undefined` | Year to display the calendar for. | #### Usage Guidelines - Use for date selection interfaces - Consider date range limitations - Provide clear visual feedback for selected dates - Handle disabled dates appropriately #### Content Guidelines - Use clear date formatting - Provide helpful date labels - Use consistent date terminology - Consider localization for date display (e.g. locale prop, month/day names, first day of week) #### Accessibility Guidelines - Provide clear date selection feedback - Ensure keyboard navigation between dates - Use appropriate ARIA labels for dates - Support screen reader announcements for date changes ## @atlaskit/checkbox Package ### Checkbox component A checkbox is an input control that allows a user to select one or more options from a number of choices. - **Keywords:** checkbox, input, form, selection, choice, option, multiple - **Categories:** forms-and-input - **Status:** general-availability #### Example ```tsx import Checkbox from '@atlaskit/checkbox/checkbox'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `defaultChecked` | `boolean \| undefined` | Sets whether the checkbox begins as checked or unchecked. | | `id` | `string \| undefined` | The ID assigned to the input. | | `isChecked` | `boolean \| undefined` | Sets whether the checkbox is checked or unchecked. | | `isDisabled` | `boolean \| undefined` | Sets whether the checkbox is disabled. Don’t use a disabled checkbox if it needs to remain in the tab order for assistive technologies. | | `isIndeterminate` | `boolean \| undefined` | Sets whether the checkbox is indeterminate. This only affects the style and does not modify the isChecked property. | | `isInvalid` | `boolean \| undefined` | Marks the field as invalid. Changes style of unchecked component. | | `isRequired` | `boolean \| undefined` | Marks the field as required & changes the label style. | | `label` | `ReactChild \| undefined` | The label to be displayed to the right of the checkbox. The label is part of the clickable element to select the checkbox. | | `name` | `string \| undefined` | The name of the submitted field in a checkbox. | | `onChange` | `((e: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Function that is called whenever the state of the checkbox changes. It will be called with an object containing the react synthetic event. Use `currentTarget` to get value, name and checked. | | `value` | `string \| number \| undefined` | The value to be used in the checkbox input. This is the value that will be returned on form submission. | | `xcss` | `false \| (XCSSValue<"alignItems", DesignTokenStyles, ""> & {} & XCSSPseudo<"alignItems", never, never, DesignTokenStyles> & XCSSMediaQuery<...> & { ...; } & { ...; }) \| null \| undefined` | Bounded style API. Defining allowed styles through this prop will be supported for future component iterations. Any styles that are not allowed by this API will result in type and land blocking violations. | #### Usage Guidelines - Use for multiple choice selections from a list, or for explicit confirmation (e.g. settings) - Use indeterminate state when some but not all children in a group are selected - Group related checkboxes logically - Provide clear labels for each option - Consider default states carefully - Use Radio for single selection; Dropdown for compact single choice; Toggle for on/off #### Content Guidelines - Write short, descriptive labels; no punctuation after labels - Use consistent language across related options - Avoid negative phrasing when possible - Group related options together #### Accessibility Guidelines - Include error messages for required or invalid checkbox state - Do not use disabled if the control must stay in tab order; use validation and error message so screen reader users hear why and how to proceed - Ensure proper labeling for all checkboxes - Use clear, descriptive labels that explain the choice - Provide keyboard navigation support - Indicate required fields clearly - Use appropriate error states and messaging ## @atlaskit/code Package ### Code component Use for short code snippets inline with body text. - **Keywords:** code, snippet, inline, syntax, programming - **Categories:** data-display - **Status:** general-availability #### Example ```tsx import Code from '@atlaskit/code/code'; const _default_1: React.JSX.Element[] = [{``}]; export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Content to be rendered in the inline code block. | | `codeBidiWarningLabel` | `string \| undefined` | Label for the bidi warning tooltip. Defaults to `Bidirectional characters change the order that text is rendered. This could be used to obscure malicious code.` | | `hasBidiWarnings` | `boolean \| undefined` | When set to `false`, disables code decorating with bidi warnings. Defaults to `true`. | | `isBidiWarningTooltipEnabled` | `boolean \| undefined` | Sets whether to render tooltip with the warning or not. Intended to be disabled when used in a mobile view, such as in the editor via mobile bridge, where the tooltip could end up being cut off or otherwise not work as expected. Defaults to `true`. | #### Usage Guidelines - Use for short, inline code snippets with body text - Default styling is overridable - Consider code block vs inline code #### Content Guidelines - Use clear, readable code examples - Keep code snippets concise - Use meaningful variable names in examples #### Accessibility Guidelines - When overriding styles, ensure contrast ratio ≥ 4.5:1 for text readability - Ensure code content is announced properly by screen readers - Consider code context and meaning ### CodeBlock component A component for displaying multi-line code blocks with syntax highlighting. - **Keywords:** code, block, syntax, highlighting, multiline - **Categories:** data-display - **Status:** general-availability #### Example ```tsx import CodeBlock from '@atlaskit/code/code-block'; const exampleCodeBlock = `export default ({ name }: { name: string }) =>
Hello {name}
;`; const _default_1: React.JSX.Element[] = [ , ]; export default _default_1; ``` #### Props | Prop | Type | Description | |-|-|-| | `codeBidiWarningLabel` | `string \| undefined` | Label for the bidi warning tooltip. | | `firstLineNumber` | `number \| undefined` | Sets the number of the first line, if showLineNumbers is set to true. | | `hasBidiWarnings` | `boolean \| undefined` | When set to `false`, disables code decorating with bidi warnings. | | `highlight` | `string \| undefined` | Comma delimited lines to highlight. Example uses: - To highlight one line `highlight="3"` - To highlight a group of lines `highlight="1-5"` - To highlight multiple groups `highlight="1-5,7,10,15-20"` | | `highlightedEndText` | `string \| undefined` | Screen reader text for the end of a highlighted line. | | `highlightedStartText` | `string \| undefined` | Screen reader text for the start of a highlighted line. | | `isBidiWarningTooltipEnabled` | `boolean \| undefined` | Sets whether to render tooltip with the warning or not. Intended to be disabled when used in a mobile view, such as in the editor via mobile bridge, where the tooltip could end up being cut off or otherwise not work as expected. | | `label` | `string \| undefined` | Text used to describe that the content of the code block is scrollable. Set only if the code block is scrollable. Defaults to 'Scrollable content'. | | `language` | `SupportedLanguages \| undefined` | Language reference designed to be populated from `SUPPORTED_LANGUAGES` in `design-system/code`. Run against language grammars from PrismJS (full list available at [PrismJS documentation](https://prismjs.com/#supported-languages)). When set to "text" will not perform highlighting. If unsupported language provided - code will be treated as "text" with no highlighting. | | `shouldShowLineNumbers` | `boolean \| undefined` | Sets whether to display code line numbers or not. | | `shouldWrapLongLines` | `boolean \| undefined` | Sets whether long lines will create a horizontally scrolling container. When set to `true`, these lines will visually wrap instead. | | `text` | `string` | The code to be formatted. (required) | #### Usage Guidelines - Use for multi-line code examples - Specify appropriate language for syntax highlighting - Consider code block sizing and scrolling - Use for code snippets that need formatting #### Content Guidelines - Use clear, readable code examples - Consider code formatting and indentation - Use meaningful variable names in examples - Keep code blocks focused and relevant #### Accessibility Guidelines - Ensure code blocks are announced properly by screen readers - Use appropriate contrast for code readability - Consider code context and meaning - Provide proper language identification ## @atlaskit/comment Package ### Comment component A component for displaying comments and discussions. - **Keywords:** comment, discussion, thread, conversation, chat - **Categories:** data-display - **Status:** general-availability #### Example ```tsx import Comment from '@atlaskit/comment/comment'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `actions` | `React.ReactNode[] \| undefined` | A list of `CommentAction` items rendered as a row of buttons below the content. | | `afterContent` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Content that is rendered after the comment's content. | | `author` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | A `CommentAuthor` element containing the name of the author. | | `avatar` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The element to display as the avatar. It's best to use `@atlaskit/avatar`. (required) | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Provide nested comments as children. | | `content` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The main content for the comment. | | `edited` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | A `CommentEdited` element which displays next to the time. Indicates whether the comment has been edited. | | `errorActions` | `React.ReactNode[] \| undefined` | A list of `CommentAction` items rendered with a warning icon instead of the actions. | | `errorIconLabel` | `string \| undefined` | Text to show in the error icon label. | | `headingLevel` | `"1" \| "3" \| "2" \| "4" \| "5" \| "6" \| undefined` | Use this to set the semantic heading level of the comment. The default comment heading has an `h3` tag. Make sure that headings are in the correct order and don’t skip levels. | | `highlighted` | `boolean \| undefined` | Sets whether this comment should be highlighted. | | `id` | `string \| undefined` | An ID to be applied to the comment. | | `isError` | `boolean \| undefined` | Indicates whether the component is in an error state. Hides actions and time. | | `isSaving` | `boolean \| undefined` | Enables "optimistic saving" mode which removes actions and displays text from the `savingText` prop. | | `restrictedTo` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Text for the "restricted to" label. This will display in the top items, before the main content. | | `savingText` | `string \| undefined` | Text to show when in "optimistic saving" mode. | | `shouldHeaderWrap` | `boolean \| undefined` | Controls if the comment header should wrap. | | `shouldRenderNestedCommentsInline` | `boolean \| undefined` | Controls if nested comments are rendered at the same depth as the parent comment. | | `time` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | A `CommentTime` element containing the time to display. | | `type` | `string \| undefined` | The type of comment. This will be rendered in a lozenge at the top of the comment, before the main content. | #### Usage Guidelines - Use for comment threads and discussions - Provide clear comment attribution - Handle comment nesting appropriately - Consider comment moderation features #### Content Guidelines - Use clear, constructive comment content - Provide meaningful comment attribution - Use appropriate comment formatting - Consider comment context and purpose #### Accessibility Guidelines - Ensure proper comment structure - Provide clear comment attribution - Use appropriate heading hierarchy - Consider screen reader navigation ## @atlaskit/date-label Package ### DateLabel component A date label displays a date as a label, with an optional appearance to communicate a meaningful condition such as a due or overdue date. - **Keywords:** date, label, date label, due date, overdue, lozenge - **Categories:** status-indicators - **Status:** general-availability #### Example ```tsx /** * @jsxRuntime classic * @jsx jsx */ import { cssMap, jsx } from '@atlaskit/css'; import DateLabel from '@atlaskit/date-label/date-label'; import { token } from '@atlaskit/tokens'; const styles = cssMap({ wrapper: { display: 'flex', gap: token('space.100'), flexWrap: 'wrap', }, }); /** * Basic example showing all three appearances of DateLabel with icons (default). */ export default function Basic(): React.JSX.Element { return (
); } ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `DateLabelAppearance \| undefined` | Controls the visual style of the date label. - `neutral` — default grey border style - `warning` — orange border, used for upcoming/near-due dates - `danger` — red border, used for overdue dates | | `hasIconBefore` | `boolean \| undefined` | When `true`, an icon is displayed before the label text. The icon shown depends on the `appearance`: - `neutral` → CalendarIcon - `warning` → ClockIcon - `danger` → WarningOutlineIcon | | `iconLabel` | `string \| undefined` | The accessible label for the icon. This is passed to the icon's `label` prop and is read by screen readers to convey the icon's meaning. Defaults to a contextual string based on the `appearance`: - `neutral` → `'Calendar'` - `warning` → `'Warning'` - `danger` → `'Danger'` Set to `''` to mark the icon as decorative (when the label text alone is sufficient). | | `isSpacious` | `boolean \| undefined` | When `true`, increases the padding and height of the date label for use in more spacious layouts (e.g. forms or detail views). Sets the height to 32px and increases horizontal padding. | | `label` | `string` | The text content to display inside the date label. (required) | | `maxWidth` | `string \| number \| undefined` | The maximum width of the date label. Accepts a number (treated as px) or a string (e.g. `'50%'`). When the label text exceeds this width it will be truncated with an ellipsis. | #### Usage Guidelines - Use to display a date as a label on an object (for example a due date), not for entering or selecting a date. - Use the appearance to communicate a meaningful condition: neutral by default, warning for approaching dates, and danger for overdue or critical dates. - A leading icon is shown by default and is appearance-driven (calendar, warning, or danger). Set `hasIconBefore={false}` to hide it. - Use spacious sizing when the date label is displayed alongside buttons. - For entering or selecting a date in a form, use DatePicker from @atlaskit/datetime-picker instead. - If users need to click the date label to change the date via a dropdown, use DateLabelDropdownTrigger instead — it is purpose-built for interactive date switching. #### Content Guidelines - Keep the date format concise and consistent with the surrounding experience. - Pair the appearance with a label that makes the condition clear; do not rely on color alone. - Use a single date value per label. #### Accessibility Guidelines - Do not rely on color alone to convey a date’s condition; ensure the date text is meaningful on its own. - Ensure sufficient color contrast for the date text across all appearances. - Provide clear, descriptive text for screen readers. ### DateLabelDropdownTrigger component Date label dropdown trigger displays a date as a label and enables changing the date through a menu or popup. - **Keywords:** date, label, dropdown, trigger, date label, menu, interactive - **Categories:** status-indicators - **Status:** general-availability #### Example ```tsx /** * @jsxRuntime classic * @jsx jsx */ import { cssMap, jsx } from '@atlaskit/css'; import { DateLabelDropdownTrigger } from '@atlaskit/date-label/date-label'; import { Text } from '@atlaskit/primitives/compiled/text'; import { token } from '@atlaskit/tokens'; const styles = cssMap({ column: { display: 'flex', flexDirection: 'column', gap: token('space.200'), }, row: { display: 'flex', gap: token('space.100'), flexWrap: 'wrap', alignItems: 'center', }, }); /** * DateLabelDropdownTrigger — an interactive date label that acts as a dropdown trigger. * Renders as a button with hover, pressed, and focus ring states, plus a chevron icon. */ export default function DropdownTrigger(): React.JSX.Element { return (
Selected:
); } ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `DateLabelDropdownTriggerAppearance \| undefined` | Controls the visual style of the trigger. - `neutral` — default grey border style - `warning` — orange border, used for upcoming/near-due dates - `danger` — red border, used for overdue dates | | `aria-controls` | `string \| undefined` | Identifies the popup element that this trigger controls. Should match the `id` of the popup content for screen readers. | | `aria-expanded` | `boolean \| undefined` | Announces to assistive technology whether the popup is currently open. | | `aria-haspopup` | `boolean \| "dialog" \| undefined` | Informs assistive technology that this element triggers a popup. | | `aria-label` | `string \| undefined` | Defines a string value that labels the trigger element for assistive technology. If not provided, the `label` text is used as the accessible name. | | `hasIconBefore` | `boolean \| undefined` | When `true`, an icon is displayed before the label text. The icon shown depends on the `appearance`: - `neutral` → CalendarIcon - `warning` → ClockIcon - `danger` → WarningOutlineIcon | | `iconLabel` | `string \| undefined` | The accessible label for the leading icon. This is passed to the icon's `label` prop and is read by screen readers to convey the icon's meaning. Defaults to a contextual string based on the `appearance`: - `neutral` → `'Calendar'` - `warning` → `'Warning'` - `danger` → `'Danger'` Set to `''` to mark the icon as decorative (when the label text alone is sufficient). | | `isLoading` | `boolean \| undefined` | When `true`, a spinner replaces the chevron icon and the trigger becomes non-interactive, indicating that an async operation is in progress (for example, saving a date selection). | | `isSelected` | `boolean \| undefined` | When `true`, renders the trigger in a selected/active state using the pressed background colour for the current appearance. Use this when the associated dropdown is open or the date has been chosen. | | `isSpacious` | `boolean \| undefined` | When `true`, increases the padding and height of the trigger to 32px and uses the body font size for more spacious layouts. | | `label` | `string` | The text content to display inside the trigger (e.g. a formatted date string). (required) | | `maxWidth` | `string \| number \| undefined` | The maximum width of the trigger. Accepts a number (treated as px) or a string (e.g. `'50%'`). Label text exceeding this width is truncated with an ellipsis. | | `onClick` | `React.MouseEventHandler \| undefined` | Callback fired when the trigger button is clicked. | #### Usage Guidelines - Use to enable date selection—only open a dropdown or popup to allow changing the date. - Use spacious sizing when displayed alongside buttons. - Do not use to communicate other information about the date; use DateLabel instead for non-interactive date display. - Do not use for date entry in forms; use DatePicker from @atlaskit/datetime-picker instead. #### Content Guidelines - Keep the date format concise and consistent with the surrounding experience. - Do not rely on color alone; pair the appearance with clear date text. #### Accessibility Guidelines - Do not rely on color alone to convey a date’s condition; ensure the date text is meaningful on its own. - Ensure the trigger is operable by keyboard and exposes an accessible name. ## @atlaskit/datetime-picker Package ### DatePicker component A component for selecting date values with calendar support. - **Keywords:** date, picker, input, calendar, selection, form - **Categories:** form - **Status:** general-availability #### Example ```tsx import DatePicker from '@atlaskit/datetime-picker/date-picker'; import __noop from '@atlaskit/ds-lib/noop'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `aria-describedby` | `string \| undefined` | Used to associate accessible descriptions to the date picker. | | `autoFocus` | `boolean \| undefined` | Set the picker to autofocus on mount. | | `calendarLabel` | `string \| undefined` | The aria-label attribute associated with the calendar. | | `clearControlLabel` | `string \| undefined` | Set the `aria-label` for the clear button. Add the word "Clear" at the beginning of the clearControlLabel. For instance, for a field to set an appointment, use "Clear appointment date and time". | | `dateFormat` | `string \| undefined` | Format the date with a string that is accepted by [date-fns's format function](https://date-fns.org/v1.29.0/docs/format). When set, the default parser also uses this format (via date-fns) so displayed labels re-parse. Without `dateFormat`, parsing falls back to the locale. A custom `parseInputValue` overrides this default. Note that though we are using `date-fns` version 2, we use [the tokens from `date-fns` version 1](https://date-fns.org/v1.30.1/docs/format) under the hood. | | `defaultValue` | `string \| undefined` | The default for `value`. | | `disabled` | `string[] \| undefined` | An array of ISO dates that should be disabled on the calendar. This does not affect what users can type into the picker. | | `disabledDateFilter` | `((date: string) => boolean) \| undefined` | A filter function for disabling dates on the calendar. This does not affect what users can type into the picker. The function is called with a date string in the format `YYYY-MM-DD` and should return `true` if the date should be disabled. | | `formatDisplayLabel` | `((value: string, dateFormat: string) => string) \| undefined` | A function for formatting the date displayed in the input. By default composes together [`date-fns`'s parse method](https://date-fns.org/v1.29.0/docs/parse) and [`date-fns`'s format method](https://date-fns.org/v1.29.0/docs/format) to return a correctly formatted date string. Note that this does not affect how the input is parsed. Use `dateFormat` for default parsing of the display format, or `parseInputValue` for a custom parser. | | `id` | `string \| undefined` | Set the id of the field. Associates a `` with the field. | | `inputLabel` | `string \| undefined` | The name of the input, used when `shouldShowCalendarButton` is true. See `shouldShowCalendarButton` description for more details. | | `inputLabelId` | `string \| undefined` | The ID of the label for the input, used when `shouldShowCalendarButton` is true. See `shouldShowCalendarButton` description for more details. | | `isDisabled` | `boolean \| undefined` | Set if the picker is disabled. | | `isInvalid` | `boolean \| undefined` | Set if the picker has an invalid value. | | `isOpen` | `boolean \| undefined` | Set if the picker is open. | | `isRequired` | `boolean \| undefined` | Set the field as required. | | `label` | `string \| undefined` | Accessible name for the Date Picker Select, rendered as `aria-label`. This will override any other method of providing a label. | | `locale` | `string \| undefined` | Locale used to format the date and calendar. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). | | `maxDate` | `string \| undefined` | The latest enabled date. Dates after this are disabled on the calendar. This does not affect what users can type into the picker. | | `minDate` | `string \| undefined` | The earliest enabled date. Dates before this are disabled on the calendar. This does not affect what users can type into the picker. | | `name` | `string \| undefined` | The name of the field. | | `nextMonthLabel` | `string \| undefined` | The aria-label attribute associated with the next-month arrow. | | `onBlur` | `FocusEventHandler \| undefined` | Called when the field is blurred. | | `onChange` | `((value: string) => void) \| undefined` | Called when the value changes. The only argument is an ISO time or empty string. | | `onFocus` | `FocusEventHandler \| undefined` | Called when the field is focused. | | `openCalendarLabel` | `string \| undefined` | The label associated with the button to open the calendar, rendered via the `shouldShowCalendarButton` prop. If a `label` prop is provided, this calendar button label will be prefixed by the value of `label`. If no `label` prop is provided, this prefix should be manually added. For example, ```tsx ``` | | `parseInputValue` | `((date: string, dateFormat: string) => Date) \| undefined` | A function for parsing input characters and transforming them into a Date object. Overrides the default parser. By default, when `dateFormat` is set the input is parsed with that format via date-fns; otherwise the date string is parsed based off the locale. Note that this does not affect how the resulting value is displayed in the input. Use the `dateFormat` or `formatDisplayLabel` prop to handle how the value is displayed. | | `placeholder` | `string \| undefined` | Placeholder text displayed in input. | | `previousMonthLabel` | `string \| undefined` | The aria-label attribute associated with the previous-month arrow. | | `selectProps` | `(Omit, "aria-describedby" \| "aria-label" \| "placeholder" \| "inputId"> & { 'aria-describedby'?: undefined; 'aria-label'?: undefined; inputId?: undefined; placeholder?: undefined; } & { ...; }) \| undefined` | | | `shouldShowCalendarButton` | `boolean \| undefined` | Provides a functional calendar button that opens the calendar picker that lives on the right side of the date picker. The accessible name for this button is caculated using either the `label`, `inputLabel`, or `inputLabelId` props, along with the `openCalendarLabel` prop. | | `spacing` | `Spacing \| undefined` | The spacing for the select control. Compact is `gridSize() * 4`, default is `gridSize * 5`. | | `value` | `string \| undefined` | The ISO time used as the input value. | | `weekStartDay` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | Start day of the week for the calendar. - `0` sunday (default value) - `1` monday - `2` tuesday - `3` wednesday - `4` thursday - `5` friday - `6` saturday | #### Usage Guidelines - Use for date selection only - Provide clear date formats - Handle date validation appropriately - Consider calendar button visibility #### Content Guidelines - Use clear, descriptive labels - Provide helpful placeholder text - Keep labels concise but descriptive - Use locale prop for date format localization #### Accessibility Guidelines - Ensure proper keyboard navigation - Use appropriate date formats - Provide clear date labels - Consider screen reader announcements ### DateTimePicker component A component for selecting both date and time values. - **Keywords:** datetime, picker, date, time, input, calendar - **Categories:** form - **Status:** general-availability #### Example ```tsx import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker'; import __noop from '@atlaskit/ds-lib/noop'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `aria-describedby` | `string \| undefined` | Used to associate accessible descriptions to both the date and time picker. If you want to associate individual accessible descriptions, this should be done through the `aria-describedby` props on the `datePickerProps` and `timePickerProps`. | | `autoFocus` | `boolean \| undefined` | Set the picker to autofocus on mount. | | `clearControlLabel` | `string \| undefined` | Set the `aria-label` for the clear button. Add the word "Clear" at the beginning of the clearControlLabel. For instance, for a field to set an appointment, use "Clear appointment date and time". | | `datePickerProps` | `DatePickerBaseProps \| undefined` | Props applied to the `DatePicker`. | | `defaultValue` | `string \| undefined` | The default for `value`. | | `id` | `string \| undefined` | Set the id of the field. | | `isDisabled` | `boolean \| undefined` | Set if the field is disabled. | | `isInvalid` | `boolean \| undefined` | Set if the picker has an invalid value. | | `isRequired` | `boolean \| undefined` | Set the field as required. | | `locale` | `string \| undefined` | Locale used for formatting dates and times. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). | | `name` | `string \| undefined` | The name of the field. | | `onBlur` | `FocusEventHandler \| undefined` | Called when the field is blurred. | | `onChange` | `((value: string) => void) \| undefined` | Called when the value changes and the date / time is a complete value, or empty. The only value is an ISO string or empty string. | | `onFocus` | `FocusEventHandler \| undefined` | Called when the field is focused. | | `parseValue` | `((dateTimeValue: string, date: string, time: string, timezone: string) => { dateValue: string; timeValue: string; zoneValue: string; }) \| undefined` | Function used to parse datetime values into their date, time and timezone sub-values. * | | `spacing` | `Spacing \| undefined` | The spacing for the select control. Compact is `gridSize() * 4`, default is `gridSize() * 5`. | | `timePickerProps` | `TimePickerBaseProps \| undefined` | Props applied to the `TimePicker`. | | `value` | `string \| undefined` | The ISO time that should be used as the input value. | #### Usage Guidelines - Use for combined date and time selection - Provide clear date/time formats - Handle timezone considerations - Consider validation requirements #### Content Guidelines - Use clear, descriptive labels - Provide helpful placeholder text - Use appropriate date/time formats - Keep labels concise but descriptive - Use locale prop for date and time format localization #### Accessibility Guidelines - Ensure proper keyboard navigation - Use appropriate date/time formats - Provide clear date/time labels - Consider screen reader announcements ### TimePicker component A component for selecting time values with clock interface. - **Keywords:** time, picker, input, clock, selection, form - **Categories:** form - **Status:** general-availability #### Example ```tsx import TimePicker from '@atlaskit/datetime-picker/time-picker'; import __noop from '@atlaskit/ds-lib/noop'; const Example = (): React.JSX.Element => ( ); export default Example; ``` #### Props | Prop | Type | Description | |-|-|-| | `aria-describedby` | `string \| undefined` | Used to associate accessible descriptions to the time picker. | | `autoFocus` | `boolean \| undefined` | Set the picker to autofocus on mount. | | `clearControlLabel` | `string \| undefined` | Set the `aria-label` for the clear button. Add the word "Clear" at the beginning of the clearControlLabel. For instance, for a field to set an appointment, use "Clear appointment date and time". | | `defaultValue` | `string \| undefined` | The default for `value`. | | `formatDisplayLabel` | `((time: string, timeFormat: string) => string) \| undefined` | A function for formatting the displayed time value in the input. By default parses with an internal time parser, and formats using the [date-fns format function]((https://date-fns.org/v1.29.0/docs/format)). Note that this does not affect how the input is parsed. This must be done using the `parseInputValue` prop. | | `hideIcon` | `boolean \| undefined` | Hides icon for dropdown indicator. | | `id` | `string \| undefined` | Set the id of the field. Associates a `` with the field. | | `isDisabled` | `boolean \| undefined` | Set if the field is disabled. | | `isInvalid` | `boolean \| undefined` | Set if the picker has an invalid value. | | `isOpen` | `boolean \| undefined` | Set if the dropdown is open. Will be `false` if not provided. | | `isRequired` | `boolean \| undefined` | Set the field as required. | | `label` | `string \| undefined` | Accessible name for the Time Picker Select, rendered as `aria-label`. This will override any other method of providing a label. | | `locale` | `string \| undefined` | Locale used to format the time. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). | | `name` | `string \| undefined` | The name of the field. | | `onBlur` | `FocusEventHandler \| undefined` | Called when the field is blurred. | | `onChange` | `((value: string) => void) \| undefined` | Called when the value changes. The only argument is an ISO time or empty string. | | `onFocus` | `FocusEventHandler \| undefined` | Called when the field is focused. | | `openTimeLabel` | `string \| undefined` | The accessible label for the button that opens the time picker. When `label` is provided, it is prefixed to this label. | | `parseInputValue` | `((time: string, timeFormat: string) => string \| Date) \| undefined` | A function for parsing input characters and transforming them into either a string or a Date object. By default parses the string based off the locale. Note that this does not affect how the resulting value is displayed in the input. To handle this, use either the `timeFormat` or `formatDisplayLabel` prop. | | `placeholder` | `string \| undefined` | Placeholder text displayed in input. | | `selectProps` | `DateTimePickerSelectProps \| undefined` | | | `shouldShowTimeButton` | `boolean \| undefined` | Provides a functional clock button that opens the time picker. When enabled, focusing the input with the keyboard does not open the menu; use this button, click the input, or type to open it instead. | | `spacing` | `Spacing \| undefined` | The spacing for the select control. Compact is `gridSize() * 4`, default is `gridSize * 5`. | | `timeFormat` | `string \| undefined` | Format the time with a string that is accepted by [date-fns's format function](https://date-fns.org/v1.29.0/docs/format). **This does not affect how the input is parsed.** This must be done using the `parseInputValue` prop. Note that though we are using `date-fns` version 2, we use [the tokens from `date-fns` version 1](https://date-fns.org/v1.30.1/docs/format) under the hood. | | `timeIsEditable` | `boolean \| undefined` | Set if users can edit the input, allowing them to add custom times. | | `times` | `string[] \| undefined` | The times shown in the dropdown. | | `value` | `string \| undefined` | The ISO time that should be used as the input value. | #### Usage Guidelines - Use for time selection only - Provide clear time formats - Handle time validation appropriately - Consider editable time input #### Content Guidelines - Use clear, descriptive labels - Provide helpful placeholder text - Use appropriate time formats - Keep labels concise but descriptive - Use locale prop for time format localization (e.g. 12h vs 24h) #### Accessibility Guidelines - Ensure proper keyboard navigation - Use appropriate time formats - Provide clear time labels - Consider screen reader announcements ## @atlaskit/dropdown-menu Package ### DropdownItem component A dropdown item populates the dropdown menu with items. Use for links or actions; every item must be inside a DropdownItemGroup. Can also be used as the trigger for a nested submenu. - **Keywords:** dropdown, menu, item, action, link, menuitem - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import MoreIcon from '@atlaskit/icon/core/show-more-horizontal'; const Examples = (): React.JSX.Element => ( <> ( )} > Dashboard Create Delete Export Share ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `"danger" \| undefined` | | | `aria-expanded` | `boolean \| undefined` | | | `aria-haspopup` | `boolean \| "grid" \| "dialog" \| "menu" \| "listbox" \| "tree" \| undefined` | An optional boolean value used to indicate if the dropdown item has popup or not. | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Primary content for the item. (required) | | `component` | `ComponentType> \| undefined` | Custom component to render as an item. Should be wrapped in `forwardRef` to avoid accessibility issues when controlling keyboard focus. | | `description` | `string \| global.JSX.Element \| undefined` | Description of the item. This will render smaller text below the primary text of the item as well as slightly increasing the height of the item. | | `elemAfter` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Element to render after the item text. Generally should be an [icon](https://atlaskit.atlassian.com/packages/design-system/icon) component. | | `elemBefore` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Element to render before the item text. Generally should be an [icon](https://atlaskit.atlassian.com/packages/design-system/icon) component. | | `hasNestedMenu` | `boolean \| undefined` | Shows a submenu indicator for custom submenu triggers. DropdownMenu triggers automatically infer this from context so you do not need to set this prop manually. Only set it manually if you are using a trigger other than DropdownMenu trigger (e.g. Popup trigger) | | `href` | `string \| undefined` | Link to another page. | | `isDisabled` | `boolean \| undefined` | Makes the element appear disabled. This will remove interactivity and the item won't appear in the focus order. | | `isSelected` | `boolean \| undefined` | Makes the element appear selected. | | `onClick` | `((e: MouseEvent \| KeyboardEvent) => void) \| undefined` | Event that is triggered when the element is clicked. | | `rel` | `string \| undefined` | The relationship of the linked URL as space-separated link types. Generally you'll want to set this to "noopener noreferrer" when `target` is "_blank". | | `returnFocusRef` | `RefObject \| undefined` | If ref is passed, focus returns to that specific ref element after dropdown item clicked. | | `role` | `string \| undefined` | An optional string value that specifies the role of the dropdown item. Use this to indicate whether the item is or presentational (e.g., 'presentation') for accessibility purposes. If not specified, it defaults to role="menuitem". | | `shortcut` | `string[] \| undefined` | | | `shouldDescriptionWrap` | `boolean \| undefined` | When `true` the description of the item will wrap multiple lines if it exceeds the width of the dropdown menu. | | `shouldTitleWrap` | `boolean \| undefined` | When `true` the title of the item will wrap multiple lines if it exceeds the width of the dropdown menu. | | `target` | `string \| undefined` | Where to display the linked URL, see [anchor information](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) on mdn for more information. | | `title` | `string \| undefined` | Adds a title attribute to the root item element. | #### Usage Guidelines - Use inside DropdownMenu with DropdownItemGroup (required parent) - Use for links (href) or actions (onClick); verbs for actions, nouns for links; no articles; single line per item - For a nested submenu: use as the trigger (pass triggerRef and trigger props, use elemAfter e.g. chevron); keep to maximum two layers #### Content Guidelines - Use clear, descriptive menu item labels - Keep menu item text concise - Use consistent terminology across menu items #### Accessibility Guidelines - Avoid truncation—ensure max width does not cut off labels - Ensure keyboard navigation with arrow keys ### DropdownItemGroup component Wrapping element for dropdown menu items. Use to group related items; optional short uppercase title (e.g. "Edit page", "Tools") separates sections. - **Keywords:** dropdown, menu, group, section, title - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import MoreIcon from '@atlaskit/icon/core/show-more-horizontal'; const Examples = (): React.JSX.Element => ( <> ( )} > Dashboard Create Delete Export Share ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Children of the section. This should generally be `Item` or `Heading` components, but can also be [`EmptyState`](https://atlaskit.atlassian.com/packages/design-system/empty-state)s if you want to render errors. (required) | | `hasSeparator` | `boolean \| undefined` | Use this to render a border at the top of the section. | | `id` | `string \| undefined` | Unique identifier for the element. | | `isList` | `boolean \| undefined` | If your menu contains a list, use this to add `
    ` and `
  • ` tags around the items. This is essential for offering better, accessible semantic markup in a list of items. | | `isScrollable` | `boolean \| undefined` | Enables scrolling within the section. This won't work unless `maxHeight` is set on the parent `MenuGroup` component. | | `label` | `string \| undefined` | Provide an accessible label for the section via `aria-label` for assistive technology. | | `title` | `string \| undefined` | The text passed into the internal `HeadingItem`. If a title isn't provided, the `HeadingItem` won't be rendered, and this component will act as a regular `Section`. | | `titleId` | `string \| undefined` | ID referenced by the menu group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group title element. Usage of either this, or the `label` attribute is strongly recommended. | #### Usage Guidelines - Use inside DropdownMenu to group related items - Use short, uppercase title to describe the group - Nested menu: maximum two layers #### Content Guidelines - Group related actions logically - Use consistent terminology across menu items #### Accessibility Guidelines - Provide clear group titles - Nested menu: maximum two layers ### DropdownItemCheckbox component A dropdown menu item with checkbox selection. Use for multiple selection from a list (e.g. status filters, show/hide toggles). - **Keywords:** dropdown, menu, checkbox, multi-select, toggle - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import MoreIcon from '@atlaskit/icon/core/show-more-horizontal'; const Examples = (): React.JSX.Element => ( <> ( )} > Dashboard Create Delete Export Share ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Primary content for the item. (required) | | `defaultSelected` | `boolean \| undefined` | Sets whether the checkbox begins selected. | | `description` | `string \| JSX.Element \| undefined` | Description of the item. This will render smaller text below the primary text of the item as well as slightly increasing the height of the item. | | `id` | `string` | Unique id of a checkbox. (required) | | `isDisabled` | `boolean \| undefined` | Makes the checkbox appear disabled as well as removing interactivity. | | `isSelected` | `boolean \| undefined` | Sets whether the checkbox is checked or unchecked. | | `onClick` | `((e: React.MouseEvent \| React.KeyboardEvent) => void) \| undefined` | Event that is triggered when the checkbox is clicked. | | `shortcut` | `Shortcut \| undefined` | | | `shouldDescriptionWrap` | `boolean \| undefined` | When `true` the description of the item will wrap multiple lines if it's long enough. | | `shouldTitleWrap` | `boolean \| undefined` | When `true` the title of the item will wrap multiple lines if it's long enough. | | `title` | `string \| undefined` | Adds a title attribute to the root item element. | #### Usage Guidelines - Use with DropdownItemCheckboxGroup; control selection with isSelected and onClick - Use for multiple selection from a list or toggles (e.g. categories, column visibility) - Group related checkboxes; use short uppercase title on DropdownItemCheckboxGroup #### Content Guidelines - Use clear, descriptive labels - Keep menu item text concise #### Accessibility Guidelines - Ensure keyboard navigation and clear selection state - Use appropriate ARIA attributes ### DropdownItemCheckboxGroup component Groups DropdownItemCheckbox components for multi-select options within a dropdown menu. - **Keywords:** dropdown, menu, checkbox, group, multi-select - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import React, { useState } from 'react'; import { DropdownItemCheckbox } from '@atlaskit/dropdown-menu/dropdown-item-checkbox'; import { DropdownItemCheckboxGroup } from '@atlaskit/dropdown-menu/dropdown-item-checkbox-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; const DropdownItemCheckboxExample = (): React.JSX.Element => { const [checked, setChecked] = useState>({ todo: true, }); const toggle = (name: string) => { setChecked((prev) => ({ ...prev, [name]: !prev[name], })); }; return ( toggle('todo')} isSelected={checked['todo']}> To do toggle('inprogress')} isSelected={checked['inprogress']} > In progress toggle('done')} isSelected={checked['done']}> Done ); }; export default DropdownItemCheckboxExample; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Children of the section. This should generally be `Item` or `Heading` components, but can also be [`EmptyState`](https://atlaskit.atlassian.com/packages/design-system/empty-state)s if you want to render errors. (required) | | `hasSeparator` | `boolean \| undefined` | Use this to render a border at the top of the section. | | `id` | `string` | Unique identifier for the checkbox group. (required) | | `isList` | `boolean \| undefined` | If your menu contains a list, use this to add `
      ` and `
    • ` tags around the items. This is essential for offering better, accessible semantic markup in a list of items. | | `isScrollable` | `boolean \| undefined` | Enables scrolling within the section. This won't work unless `maxHeight` is set on the parent `MenuGroup` component. | | `label` | `string \| undefined` | Provide an accessible label for the section via `aria-label` for assistive technology. | | `title` | `string \| undefined` | The text passed into the internal `HeadingItem`. If a title isn't provided, the `HeadingItem` won't be rendered, and this component will act as a regular `Section`. | | `titleId` | `string \| undefined` | ID referenced by the menu group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group title element. Usage of either this, or the `label` attribute is strongly recommended. | #### Usage Guidelines - Use to group related DropdownItemCheckbox items - Use for multiple selection from a list #### Content Guidelines - Group related checkboxes logically - Use consistent terminology ### DropdownItemRadio component A dropdown menu item with radio selection. Use for single selection from a short list (e.g. view mode, sort order). - **Keywords:** dropdown, menu, radio, single-select, choice - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import MoreIcon from '@atlaskit/icon/core/show-more-horizontal'; const Examples = (): React.JSX.Element => ( <> ( )} > Dashboard Create Delete Export Share ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Primary content for the item. (required) | | `defaultSelected` | `boolean \| undefined` | Sets whether the checkbox begins selected. | | `description` | `string \| JSX.Element \| undefined` | Description of the item. This will render smaller text below the primary text of the item as well as slightly increasing the height of the item. | | `id` | `string` | Unique ID of the checkbox. (required) | | `isDisabled` | `boolean \| undefined` | Makes the checkbox appear disabled as well as removing interactivity. | | `isSelected` | `boolean \| undefined` | Sets whether the checkbox is checked or unchecked. | | `onClick` | `((e: React.MouseEvent \| React.KeyboardEvent) => void) \| undefined` | Event that is triggered when the checkbox is clicked. | | `shortcut` | `Shortcut \| undefined` | | | `shouldDescriptionWrap` | `boolean \| undefined` | When `true` the description of the item will wrap multiple lines if it's long enough. | | `shouldTitleWrap` | `boolean \| undefined` | When `true` the title of the item will wrap multiple lines if it's long enough. | | `title` | `string \| undefined` | Adds a title attribute to the root item element. | #### Usage Guidelines - Use with DropdownItemRadioGroup; control selection with isSelected and onClick - Use for single selection from a short list (e.g. views, density) - Group related radio items; use short uppercase title on DropdownItemRadioGroup #### Content Guidelines - Use clear, descriptive labels - Keep menu item text concise #### Accessibility Guidelines - Ensure keyboard navigation and clear selection state - Use appropriate ARIA attributes ### DropdownItemRadioGroup component Groups DropdownItemRadio components for single-select options within a dropdown menu. - **Keywords:** dropdown, menu, radio, group, single-select - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import React, { useState } from 'react'; import { DropdownItemRadio } from '@atlaskit/dropdown-menu/dropdown-item-radio'; import { DropdownItemRadioGroup } from '@atlaskit/dropdown-menu/dropdown-item-radio-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; const DropdownItemRadioExample = (): React.JSX.Element => { const [selected, setSelected] = useState('detail'); return ( setSelected('detail')} isSelected={selected === 'detail'} > Detail view setSelected('list')} isSelected={selected === 'list'} > List view ); }; export default DropdownItemRadioExample; ``` #### Props | Prop | Type | Description | |-|-|-| | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Children of the section. This should generally be `Item` or `Heading` components, but can also be [`EmptyState`](https://atlaskit.atlassian.com/packages/design-system/empty-state)s if you want to render errors. (required) | | `hasSeparator` | `boolean \| undefined` | Use this to render a border at the top of the section. | | `id` | `string` | (required) | | `isList` | `boolean \| undefined` | If your menu contains a list, use this to add `
        ` and `
      • ` tags around the items. This is essential for offering better, accessible semantic markup in a list of items. | | `isScrollable` | `boolean \| undefined` | Enables scrolling within the section. This won't work unless `maxHeight` is set on the parent `MenuGroup` component. | | `label` | `string \| undefined` | Provide an accessible label for the section via `aria-label` for assistive technology. | | `title` | `string \| undefined` | The text passed into the internal `HeadingItem`. If a title isn't provided, the `HeadingItem` won't be rendered, and this component will act as a regular `Section`. | | `titleId` | `string \| undefined` | ID referenced by the menu group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group title element. Usage of either this, or the `label` attribute is strongly recommended. | #### Usage Guidelines - Use to group related DropdownItemRadio items - Use for single selection from a short list #### Content Guidelines - Group related radio items logically - Use consistent terminology ### DropdownMenu component A dropdown menu component for displaying contextual actions and options. - **Keywords:** dropdown, menu, overflow, actions, options, popup, contextual - **Categories:** navigation - **Status:** general-availability #### Example ```tsx import IconButton from '@atlaskit/button/icon/button'; import { DropdownItem } from '@atlaskit/dropdown-menu/dropdown-item'; import { DropdownItemGroup } from '@atlaskit/dropdown-menu/dropdown-item-group'; import { DropdownMenu } from '@atlaskit/dropdown-menu/dropdown-menu'; import MoreIcon from '@atlaskit/icon/core/show-more-horizontal'; const Examples = (): React.JSX.Element => ( <> ( )} > Dashboard Create Delete Export Share ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `appearance` | `"default" \| "tall" \| undefined` | Controls the appearance of the menu. The default menu will scroll after its height exceeds the pre-defined amount. The tall menu won't scroll until the height exceeds the height of the viewport. | | `autoFocus` | `boolean \| undefined` | Controls if the first menu item receives focus when menu is opened. Note that the menu has a focus lock which traps the focus within the menu. The first item gets focus automatically if the menu is triggered using the keyboard. | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Content that will be rendered inside the layer element. Should typically be `DropdownItemGroup` or `DropdownItem`, or the checkbox and radio variants of those. | | `defaultOpen` | `boolean \| undefined` | Controls the initial open state of the dropdown. If provided, the component is considered to be controlled which means that the user is responsible for managing the open and close state of the menu. Using `defaultOpen` may cause accessiblity issues because it will automatically shift focus to the first menu item; which can be disorienting. Only use this if action on the menu is required to proceed. | | `isLoading` | `boolean \| undefined` | If true, a spinner is rendered instead of the items. | | `isOpen` | `boolean \| undefined` | Controls the open state of the dropdown. | | `label` | `string \| undefined` | Provide an accessible label via `aria-label` for assistive technology. | | `menuLabel` | `string \| undefined` | Provide an accessible label for the menu element for assistive technology. | | `onOpenChange` | `((args: OnOpenChangeArgs) => void) \| undefined` | Called when the menu should be open/closed. Receives an object with `isOpen` state. If the dropdown was closed programatically, the `event` parameter will be `null`. | | `placement` | `Placement \| undefined` | Position of the menu. | | `returnFocusRef` | `React.RefObject \| undefined` | If ref is passed, focus returns to that specific ref element after dropdown dismissed. | | `shouldFitContainer` | `boolean \| undefined` | This fits the dropdown menu width to its parent's width. When set to `true`, the trigger and dropdown menu elements will be wrapped in a `div` with `position: relative`. The dropdown menu will be rendered as a sibling to the trigger element, and will be full width. The default is `false`. This fits the dropdown menu width to its parent's width. When set to `true`, the trigger and dropdown menu elements will be wrapped in a `div` with `position: relative`. The dropdown menu will be rendered as a sibling to the trigger element, and will be full width. The default is `false`. | | `shouldIgnoreCloseEvent` | `((event: Event \| React.MouseEvent \| React.KeyboardEvent) => boolean) \| undefined` | Allows consumers to ignore specific close events, for example when an external overlay should be treated as part of the dropdown interaction. | | `spacing` | `"compact" \| "cozy" \| "spacious" \| undefined` | Controls the spacing density of the menu. NOTE: `cozy` is deprecated and will be removed. `spacious` replaces `cozy` and results in the same visual appearance. | | `statusLabel` | `string \| undefined` | Text to be used as status for assistive technologies. Defaults to "Loading". | | `trigger` | `string \| ((triggerButtonProps: CustomTriggerProps) => React.ReactElement>) \| undefined` | Content that triggers the dropdown menu to open and close. Use with `triggerType` to get a button trigger. To customize the trigger element, provide a function to this prop. You can find [examples for custom triggers](https://atlassian.design/components/dropdown-menu/examples#custom-triggers) in our documentation. | #### Usage Guidelines - Use for 5–15 items; navigation or command (action on selection) - Avoid truncation—check max width; avoid truncated labels - Nested menu: maximum two layers - In a modal, use shouldRenderToParent for correct focus and screen reader behavior - Disabled triggers are not supported (see Button a11y) - Use Select for search/select; Checkbox for multiple from list; Radio for short single choice #### Content Guidelines - Logical order (e.g. most selected first); group with uppercase section title - Use verbs for actions, nouns for links; no articles; single line per item - Use clear, descriptive menu item labels - Keep menu item text concise - Group related actions logically - Use consistent terminology across menu items #### Accessibility Guidelines - Avoid truncation—ensure max width does not cut off labels - Focus lock when open; keyboard open should focus first item - Nested menu: maximum two layers - In modal use shouldRenderToParent for focus and voicing - Provide clear labels for dropdown triggers - Ensure keyboard navigation with arrow keys - Use appropriate ARIA attributes ## @atlaskit/dynamic-table Package ### Dynamic table component A dynamic table displays rows of data with built-in pagination, sorting, and re-ordering functionality. - **Keywords:** table, dynamic-table, data, sortable, rows, columns, sorting, pagination, drag and drop, ranking - **Categories:** data display - **Status:** general-availability #### Example ```tsx import DynamicTable from '@atlaskit/dynamic-table/stateful'; import { head, rows } from './content/sample-data'; export default function TableUncontrolled(): React.JSX.Element { return ( ); } ``` #### Example ```tsx import React, { useState } from 'react'; import Banner from '@atlaskit/banner/banner'; import ButtonGroup from '@atlaskit/button/button-group'; import Button from '@atlaskit/button/default/button'; import { cssMap } from '@atlaskit/css'; import DynamicTableStateless from '@atlaskit/dynamic-table/stateless'; import WarningIcon from '@atlaskit/icon/core/status-warning'; import { Flex } from '@atlaskit/primitives/compiled/flex'; import { token } from '@atlaskit/tokens'; import { head, rows } from './content/sample-data'; const iconSpacingStyles = cssMap({ space050: { paddingBlock: token('space.050'), paddingInline: token('space.050'), }, }); export default function TableControlled(): React.JSX.Element { const [pageNumber, setPageNumber] = useState(3); const navigateTo = (pageNumber: number) => { setPageNumber(pageNumber); }; return ( <> } > This is a stateless table example, which doesn't have pagination support. To navigate pages, use the "Previous page" and "Next page" buttons. console.log('onSort')} onSetPage={() => console.log('onSetPage')} /> ); } ``` #### Props | Prop | Type | Description | |-|-|-| | `caption` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal \| null \| undefined` | Caption for the table styled as a heading. This appears before the table header, and is announced when people who use assistive technology land on the table. If you don’t want the caption to appear on the page but do want it to be available for assistive technology, surround the caption with ``. | | `defaultPage` | `number \| undefined` | When the table is initially rendered, use this to set which page number is shown by default. In most circumstances, people will expect this to be page `1`. | | `defaultSortKey` | `string \| undefined` | Sets which column the rows should be sorted by when the table is initially rendered. Corresponds to the `key`'s defined in the `head` prop. | | `defaultSortOrder` | `SortOrderType \| undefined` | Default column sort order used when initially rendering. Defaults to `"ASC"`. | | `emptyView` | `ReactElement> \| undefined` | Shown when the table has no content. | | `head` | `HeadType \| undefined` | Cells to be placed in the head of the table. Never put controls, like links and buttons in the table header. Each element in the head creates a new column. | | `highlightedRowIndex` | `number \| number[] \| undefined` | Use this to set if the row will be highlighted. Never use highlighted rows to indicate that a person has selected or focused on the row. | | `isFixedSize` | `boolean \| undefined` | Use this to force columns to use their initial width regardless of the size of the content that loads in. | | `isLoading` | `boolean \| undefined` | Displays a loading spinner overlaid on top of the current page. | | `isRankable` | `boolean \| undefined` | Use this to enable drag and drop sorting of table rows. | | `isRankingDisabled` | `boolean \| undefined` | Disables being able to drop rows on the table. We recommend using `isRankable` instead of this prop, and it will be deprecated in a future release. | | `label` | `string \| undefined` | If you don’t use a caption, then you’ll need to use label to describe the table for assistive technologies. Avoid using both at the same time as they may conflict. Rather than a screen reader speaking "Entering table", passing in an label allows a custom message like "Entering Jira work items table". | | `loadingLabel` | `string \| undefined` | Use this to set a label for assistive technology that describes the loading state. The default label is "Loading table". You can customize this to be more specific to your table, for example “Loading work items table”. | | `loadingSpinnerSize` | `LoadingSpinnerSizeType \| undefined` | Configuration of the loading spinner shown when `isLoading` is true. Defaults to `"large"` when a page has more than two rows, else `"small"`. | | `onPageRowsUpdate` | `((pageRows: RowType[]) => void) \| undefined` | A callback that happens when the rows displayed on a page have changed. | | `onRankEnd` | `((rankEnd: RankEnd) => void) \| undefined` | A callback that happens when a drop of a row has completed. | | `onRankStart` | `((rankStart: RankStart) => void) \| undefined` | A callback that happens when a drag of a row has started. | | `onSetPage` | `((page: number, UIAnalyticsEvent?: UIAnalyticsEvent \| undefined) => void) \| undefined` | A callback that happens when the table page has changed. | | `onSort` | `((data: any, UIAnalyticsEvent?: UIAnalyticsEvent \| undefined) => void) \| undefined` | A callback that happens when a column heading has been sorted. Use this to provide custom sorting. | | `page` | `number \| undefined` | Page the table should show. | | `paginationi18n` | `I18nShape \| undefined` | Labels for the previous and next buttons used in pagination. Defaults to `"Previous"` and `"Next"`. | | `rows` | `RowType[] \| undefined` | Rows to be placed in the table. Each row contains cells which should map to the ones defined in the head. Rows accept standard HTML props in addition to those listed below. Ensure each cell has a unique `key` per column - this is used for both React's reconciliation of lists and column sorting. | | `rowsPerPage` | `number \| undefined` | Use this to control how many rows should be displayed per page. If the number of rows exceed one page, this will enable pagination. | | `sortKey` | `string \| undefined` | Column key that the rows should be sorted by. Corresponds to the `key`'s defined in the `head` prop. | | `sortOrder` | `SortOrderType \| undefined` | Column sort order. | ### DynamicTableStateless component A stateless dynamic table for when you need to control pagination, sorting, and data externally. Use when integrating with custom state management. - **Keywords:** table, dynamic-table, stateless, controlled, pagination, sorting - **Categories:** data display - **Status:** general-availability #### Example ```tsx import React, { useState } from 'react'; import Banner from '@atlaskit/banner/banner'; import ButtonGroup from '@atlaskit/button/button-group'; import Button from '@atlaskit/button/default/button'; import { cssMap } from '@atlaskit/css'; import DynamicTableStateless from '@atlaskit/dynamic-table/stateless'; import WarningIcon from '@atlaskit/icon/core/status-warning'; import { Flex } from '@atlaskit/primitives/compiled/flex'; import { token } from '@atlaskit/tokens'; import { head, rows } from './content/sample-data'; const iconSpacingStyles = cssMap({ space050: { paddingBlock: token('space.050'), paddingInline: token('space.050'), }, }); export default function TableControlled(): React.JSX.Element { const [pageNumber, setPageNumber] = useState(3); const navigateTo = (pageNumber: number) => { setPageNumber(pageNumber); }; return ( <> } > This is a stateless table example, which doesn't have pagination support. To navigate pages, use the "Previous page" and "Next page" buttons. console.log('onSort')} onSetPage={() => console.log('onSetPage')} /> ); } ``` #### Props | Prop | Type | Description | |-|-|-| | `caption` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Caption for the table styled as a heading. This appears before the table header, and is announced when people who use assistive technology land on the table. If you don’t want the caption to appear on the page but do want it to be available for assistive technology, surround the caption with ``. | | `emptyView` | `React.ReactElement> \| undefined` | Shown when the table has no content. | | `head` | `HeadType \| undefined` | Cells to be placed in the head of the table. Each element in the head creates a new column. | | `highlightedRowIndex` | `number \| number[] \| undefined` | Use this to set which rows will be highlighted. Never use highlighted rows to indicate that a person has selected or focused on the row. | | `isFixedSize` | `boolean \| undefined` | Use this to force columns to use their initial width regardless of the size of the content that loads in. | | `isLoading` | `boolean \| undefined` | Displays a loading spinner overlaid on top of the current page. | | `isRankable` | `boolean \| undefined` | Use this to enable drag and drop sorting of table rows. | | `isRankingDisabled` | `boolean \| undefined` | Disables being able to drop rows on the table. We recommend using `isRankable` instead of this prop, and it will be deprecated in a future release. | | `label` | `string \| undefined` | If you don’t use a caption, then you’ll need to use label to describe the table for assistive technologies. Avoid using both at the same time as they may conflict. Rather than a screen reader speaking "Entering table", passing in an label allows a custom message like "Entering Jira work items table". | | `loadingLabel` | `string \| undefined` | Accessible name for loading states spinner. Can be used for internationalization. Default is "Loading table". | | `loadingSpinnerSize` | `LoadingSpinnerSizeType \| undefined` | Sets the size of the loading spinner when `isLoading` is true. Defaults to `"large"` when a page has more than two rows, otherwise it will be `"small"`. | | `onPageRowsUpdate` | `((pageRows: RowType[]) => void) \| undefined` | A callback that happens when the rows displayed on a page have changed. | | `onRankEnd` | `((rankEnd: RankEnd, uiAnalyticsEvent?: UIAnalyticsEvent \| undefined) => void) \| undefined` | A callback that happens when a drop of a row has completed. | | `onRankStart` | `((rankStart: RankStart) => void) \| undefined` | A callback that happens when a drag of a row has started. | | `onSetPage` | `((page: number, UIAnalyticsEvent?: UIAnalyticsEvent \| undefined) => void) \| undefined` | A callback that happens when the table page has changed. Use this when you want to control the pagination of the table. | | `onSort` | `((data: any, UIAnalyticsEvent?: UIAnalyticsEvent \| undefined) => void) \| undefined` | A callback that happens when a column heading has been sorted. Use this to provide custom sorting for the table. | | `page` | `number \| undefined` | Page the table should show. Set by default to 1, so that it's never undefined. | | `paginationi18n` | `I18nShape \| undefined` | Labels for the pagination wrapper, previous and next buttons used in pagination. Defaults to `"Page"`, `"Pagination"`, `"Previous"` and `"Next"`. | | `rows` | `RowType[] \| undefined` | Rows to be placed in the table. Each row contains cells which should map to the ones defined in the head. Ensure each cell has a unique `key` per column - this is used for both Reacts reconcilation of lists and column sorting. | | `rowsPerPage` | `number \| undefined` | Controls how many rows should be displayed per page. | | `sortKey` | `string \| undefined` | Column key that the rows should be sorted by. Corresponds to the `key`'s defined in the `head` prop. | | `sortOrder` | `SortOrderType \| undefined` | Column sort order. | | `totalRows` | `number \| undefined` | Total number of rows, in case of paginated data. | #### Usage Guidelines - Use when you need to control table state externally (e.g. server-side pagination, custom sort logic) - Use DynamicTable (stateful) when built-in pagination and sorting are sufficient ## @atlaskit/empty-state Package ### EmptyState component A component for when there is nothing to display (no tasks, cleared inbox, no results). - **Keywords:** empty, state, results, placeholder, no-content, void - **Categories:** status - **Status:** general-availability #### Example ```tsx import EmptyState from '@atlaskit/empty-state/empty-state'; const Examples = (): React.JSX.Element => ( <> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `buttonGroupLabel` | `string \| undefined` | Accessible name for the action buttons group of empty state. Can be used for internationalization. Default is "Button group". | | `description` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The main block of text that holds additional supporting information. | | `header` | `string` | Title that briefly describes the page to the user. (required) | | `headingLevel` | `number \| undefined` | The value used to set the heading level of the header element. Must be in the range of 1 to 6. Defaults to 4. | | `headingSize` | `"xsmall" \| "medium" \| undefined` | The keyword used to set the visual appearance of the header element. Defaults to "medium". "xsmall" can be used for empty states in smaller contexts such as popups. | | `imageHeight` | `number \| undefined` | Height of the image that is rendered in EmptyState component. Useful when you want image to be of exact height to stop it bouncing around when loading in. Only set `height` if you want the image to resize down on smaller devices. | | `imageUrl` | `string \| undefined` | The url of image that will be shown above the title, fed directly into the `src` prop of an element. Note, this image will be constrained by the `maxWidth` and `maxHeight` props. | | `imageWidth` | `number \| undefined` | Width of the image that is rendered in EmptyState component. Useful when you want image to be of exact width to stop it bouncing around when loading in. | | `isLoading` | `boolean \| undefined` | Used to indicate a loading state. Will show a spinner next to the action buttons when true. | | `maxImageHeight` | `number \| undefined` | Maximum height (in pixels) of the image, default value is 160. | | `maxImageWidth` | `number \| undefined` | Maximum width (in pixels) of the image, default value is 160. | | `primaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Primary action button for the page, usually it will be something like "Create" (or "Retry" for error pages). | | `renderImage` | `((props: RenderImageProps) => React.ReactNode) \| undefined` | An alternative API to supply an image using a render prop. Only rendered if no `imageUrl` is supplied. | | `secondaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Secondary action button for the page. | | `tertiaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | Button with link to some external resource like documentation or tutorial, it will be opened in a new tab. | | `width` | `Width \| undefined` | Controls how much horizontal space the component fills. Defaults to "wide". | #### Usage Guidelines - Use when nothing to display in a view (no tasks, no results, cleared inbox) - Header is required; illustration, description, and buttons are optional - Use wide (464px) or narrow (304px) layout as appropriate - Provide one primary CTA; do not stack multiple primary buttons - Use illustration as spot only—do not resize; keep relevant, neutral or humorous - Explain why the state is empty and provide clear next steps - Consider i18n for illustrations (e.g. culturally neutral imagery, translatable alt text) #### Content Guidelines - Blank slate: inspirational, motivating tone - All done: celebratory tone - No results: neutral tone with next steps - Use clear, descriptive headers - Provide specific next steps; avoid negative language #### Accessibility Guidelines - Avoid jargon; use simple language - Use descriptive link text (not "click here") - Add alt text only if the illustration is meaningful; otherwise omit or mark decorative - Provide clear empty state messaging - Use appropriate headings and structure - Ensure actionable content is accessible ## @atlaskit/flag Package ### Flag component A component for displaying brief messages. - **Keywords:** flag, message, success, notification, alert, toast - **Categories:** feedback - **Status:** general-availability #### Example ```tsx import Flag from '@atlaskit/flag/flag'; import { FlagGroup } from '@atlaskit/flag/flag-group'; import InfoIcon from '@atlaskit/icon/core/status-information'; const Examples = (): React.JSX.Element => ( <> } title="Success" description="Your changes have been saved successfully." appearance="success" /> } title="Warning" description="This action cannot be undone." appearance="warning" actions={[ { content: 'Proceed', onClick: () => console.log('Proceed clicked'), }, ]} /> } title="Error" description="Something went wrong. Please try again." appearance="error" actions={[ { content: 'Retry', onClick: () => console.log('Retry clicked'), }, ]} /> ); export default Examples; ``` #### Props | Prop | Type | Description | |-|-|-| | `actions` | `ActionsType \| undefined` | Array of clickable actions to be shown at the bottom of the flag. For flags where appearance is 'normal', actions will be shown as links. For all other appearance values, actions will shown as buttons. If href is passed the action will be shown as a link with the passed href prop. | | `appearance` | `AppearanceTypes \| undefined` | Makes the flag appearance bold. Setting this to anything other than 'normal' hides the dismiss button. | | `autoDismissSeconds` | `number \| undefined` | Duration in seconds before flag gets auto dismissed. Default is 8 seconds. For a11y reasons 8s is also a strongly-suggested minimum. Only applies to auto-dismissable flags. | | `delayAnnouncement` | `number \| undefined` | Milliseconds to delay the screen reader announcement due to announcement conflict. | | `description` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The secondary content shown below the flag title. | | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | Specifies the heading level in the document structure. If not specified, the default is `2`. | | `icon` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The icon displayed in the top-left of the flag. Should be an instance of `@atlaskit/icon`. Your icon will receive the appropriate default color, which you can override by setting the `color` prop on the icon to your preferred icon color. If no icon is provided, a default icon will be used based on the appearance prop. | | `id` | `string \| number` | A unique identifier used for rendering and onDismissed callbacks. (required) | | `linkComponent` | `React.ComponentType \| undefined` | A link component that is passed down to the `@atlaskit/button` used by actions, to allow custom routers to be used. See the [button with router](https://atlaskit.atlassian.com/packages/design-system/button/example/ButtonWithRouter) example of what this component should look like. | | `onBlur` | `((e: React.FocusEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Standard onBlur event, applied to Flag by AutoDismissFlag. | | `onDismissed` | `((id: string \| number, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Handler which will be called when a Flag's dismiss button is clicked. Receives the id of the dismissed Flag as a parameter. | | `onFocus` | `((e: React.FocusEvent, analyticsEvent: UIAnalyticsEvent) => void) \| undefined` | Standard onFocus event, applied to Flag by AutoDismissFlag. | | `onMouseOut` | `React.MouseEventHandler \| undefined` | Standard onMouseOut event, applied to Flag by AutoDismissFlag. | | `onMouseOver` | `React.MouseEventHandler \| undefined` | Standard onMouseOver event, applied to Flag by AutoDismissFlag. | | `title` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal \| null \| undefined` | The bold text shown at the top of the flag. (required) | #### Usage Guidelines - Use for confirmations and alerts needing minimal interaction - Position at bottom left; overlays content - Default: dismissible, event-driven (e.g. avatar update). Bold: not dismissible, severity (success/loading/warning/error), collapsed/expanded - Use Banner for critical/system messages; Inline message when action is required; Modal for immediate action #### Content Guidelines - Be clear about what went wrong for errors - Provide specific steps to resolve issues - Use a helpful, non-threatening tone - Clearly state potential consequences for warnings - Confirm outcome then get out of the way for success messages - Information: inform, no action needed - Warning: before action, empathy, offer alternative - Error: explain what went wrong and next step; use "we" not "you" - Success: confirm outcome, then get out of the way; option to view details - Be clear and concise; use a helpful, non-threatening tone #### Accessibility Guidelines - Keep copy concise for zoom and long words - Use h2 for title via `headingLevel` prop; maintain heading hierarchy - Do not stack dismissible and non-dismissible flags - Do not rely on color alone for severity - Avoid dead ends—always indicate how to proceed - Do not use auto-dismiss for critical messages - Use descriptive link text that describes the destination - Ensure flag content is announced by screen readers - Consider screen reader announcement conflicts ## @atlaskit/form Package ### CharacterCounter component Displays character count for text inputs. Can be used standalone or with CharacterCounterField. - **Keywords:** form, character, counter - **Categories:** form - **Status:** general-availability #### Example ```tsx import React, { useState } from 'react'; import { CharacterCounter } from '@atlaskit/form/character-counter'; import { Label } from '@atlaskit/form/label/default'; import { Box } from '@atlaskit/primitives/compiled/box'; import { Stack } from '@atlaskit/primitives/compiled/stack'; import TextArea from '@atlaskit/textarea/text-area'; import TextField from '@atlaskit/textfield/text-field'; /** * Standalone CharacterCounter example - used outside of Form context * This is useful when you need character counting in custom implementations * that don't use the Form component or have a specific layout requirements * that CharacterCounterField does not provide. Generally speaking, it is * recommended to use CharacterCounterField for consistent styling. */ const StandaloneCharacterCounterExample = (): React.JSX.Element => { const [textFieldValue, setTextFieldValue] = useState(''); const [textAreaValue, setTextAreaValue] = useState(''); const textFieldId = 'standalone-text-field'; const textAreaId = 'standalone-text-area'; // Character limits const maxCharacters = 50; const minCharacters = 10; const textAreaMaxCharacters = 200; // Calculate error states for styling const isTextFieldTooLong = textFieldValue.length > maxCharacters; const isTextAreaTooShort = textAreaValue.length < minCharacters; const isTextAreaTooLong = textAreaValue.length > textAreaMaxCharacters; const hasTextAreaError = isTextAreaTooShort || isTextAreaTooLong; return ( {/* Example 1: TextField with maximum character limit */} setTextFieldValue(e.currentTarget.value)} aria-describedby={`${textFieldId}-character-counter`} isInvalid={isTextFieldTooLong} /> {/* Example 2: TextArea with both minimum and maximum limits */}