# Atlassian Design System > A comprehensive design system that provides a unified set of components, tokens, primitives, and tools for building consistent, accessible, and responsive user interfaces across Atlassian apps. ## Atlassian Design System Tokens Design tokens are the single source of truth to name and store design decisions, including colors, typography, spacing, and other design primitives. Tokens come from the `@atlaskit/tokens` package, typically meaning the `token()` function call. See: https://atlassian.design/components/tokens **You must ONLY use tokens listed in this document, do not make up values.** Example: ```tsx import { css } from '@atlaskit/css'; import { token } from '@atlaskit/tokens'; const styles = css({ backgroundColor: token('elevation.surface'), color: token('color.text'), }); ``` ### Tokens list Please note all values below are examples and may not match the current theme applied to your user. #### Colors ##### Background Colors Background colors define the base layer of components and surfaces: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.background.brand.bold` | #0C66E4 | #1D7AFC | Brand elements with emphasis | | `color.background.brand.bold.hovered` | #0055CC | #388BFF | Hover state of brand.bold | | `color.background.brand.bold.pressed` | #09326C | #1D7AFC | Pressed state of brand.bold | | `color.background.brand.boldest` | #0C66E4 | #1D7AFC | Brand elements that need to stand out | | `color.background.brand.boldest.hovered` | #0055CC | #388BFF | Hover state of brand.boldest | | `color.background.brand.boldest.pressed` | #09326C | #1D7AFC | Pressed state of brand.boldest | | `color.background.brand.subtlest` | #E9F2FF | #0C66E4 | Brand elements with less emphasis | | `color.background.brand.subtlest.hovered` | #CCE0FF | #1D7AFC | Hover state of brand.subtlest | | `color.background.brand.subtlest.pressed` | #85B8FF | #1D7AFC | Pressed state of brand.subtlest | | `color.background.danger` | #FFEDEB | #4F1C16 | Critical information backgrounds | | `color.background.danger.hovered` | #FFD5D2 | #5D1F1A | Hover state of danger | | `color.background.danger.pressed` | #FFC2BE | #6D231B | Pressed state of danger | | `color.background.danger.bold` | #CA3521 | #FF9C8F | Vibrant danger backgrounds | | `color.background.danger.bold.hovered` | #AE2A19 | #FFB3A8 | Hover state of danger.bold | | `color.background.danger.bold.pressed` | #601E16 | #FF9C8F | Pressed state of danger.bold | | `color.background.discovery` | #F3F0FF | #2B2451 | Change/new feature backgrounds | | `color.background.discovery.hovered` | #DFD8FD | #352C63 | Hover state of discovery | | `color.background.discovery.pressed` | #C0B6F2 | #3D3274 | Pressed state of discovery | | `color.background.discovery.bold` | #5E4DB2 | #B8ACF6 | Vibrant discovery backgrounds | | `color.background.discovery.bold.hovered` | #4C3B9C | #C7BFFF | Hover state of discovery.bold | | `color.background.discovery.bold.pressed` | #352C63 | #B8ACF6 | Pressed state of discovery.bold | | `color.background.information` | #E9F2FF | #1C2B41 | Information/in-progress backgrounds | | `color.background.information.hovered` | #CCE0FF | #22324B | Hover state of information | | `color.background.information.pressed` | #85B8FF | #2B3E5C | Pressed state of information | | `color.background.information.bold` | #0C66E4 | #85B8FF | Vibrant information backgrounds | | `color.background.information.bold.hovered` | #0055CC | #99C7FF | Hover state of information.bold | | `color.background.information.bold.pressed` | #09326C | #85B8FF | Pressed state of information.bold | | `color.background.input` | #FFFFFF | #1D2125 | Form element backgrounds | | `color.background.input.hovered` | #F7F8F9 | #2C3338 | Hover state of input | | `color.background.input.pressed` | #F7F8F9 | #2C3338 | Pressed state of input | | `color.background.neutral` | #F7F8F9 | #2C3338 | Default neutral backgrounds | | `color.background.neutral.hovered` | #F1F2F4 | #38414A | Hover state of neutral | | `color.background.neutral.pressed` | #F1F2F4 | #38414A | Pressed state of neutral | | `color.background.neutral.subtle` | #FFFFFF | #1D2125 | Subtle neutral backgrounds | | `color.background.neutral.subtle.hovered` | #F7F8F9 | #2C3338 | Hover state of neutral.subtle | | `color.background.neutral.subtle.pressed` | #F7F8F9 | #2C3338 | Pressed state of neutral.subtle | | `color.background.neutral.bold` | #091E420F | #A1BDD914 | Vibrant neutral backgrounds | | `color.background.neutral.bold.hovered` | #091E4224 | #A1BDD924 | Hover state of neutral.bold | | `color.background.neutral.bold.pressed` | #091E4236 | #A1BDD936 | Pressed state of neutral.bold | | `color.background.selected` | #E9F2FF | #092957 | Selected element backgrounds | | `color.background.selected.hovered` | #CCE0FF | #0C3B85 | Hover state of selected | | `color.background.selected.pressed` | #85B8FF | #0C3B85 | Pressed state of selected | | `color.background.selected.bold` | #0C66E4 | #388BFF | Vibrant selected backgrounds | | `color.background.selected.bold.hovered` | #0055CC | #579DFF | Hover state of selected.bold | | `color.background.selected.bold.pressed` | #09326C | #388BFF | Pressed state of selected.bold | | `color.background.success` | #DFFCF0 | #164B35 | Success message backgrounds | | `color.background.success.hovered` | #BAF3DB | #1C5339 | Hover state of success | | `color.background.success.pressed` | #7EE2B8 | #216E4E | Pressed state of success | | `color.background.success.bold` | #1F845A | #4BCE97 | Vibrant success backgrounds | | `color.background.success.bold.hovered` | #216E4E | #6BE6B8 | Hover state of success.bold | | `color.background.success.bold.pressed` | #164B35 | #4BCE97 | Pressed state of success.bold | | `color.background.warning` | #FFF7D6 | #533F04 | Warning message backgrounds | | `color.background.warning.hovered` | #F8E6A0 | #624F0A | Hover state of warning | | `color.background.warning.pressed` | #F5CD47 | #7F5F01 | Pressed state of warning | | `color.background.warning.bold` | #B38600 | #E2B203 | Vibrant warning backgrounds | | `color.background.warning.bold.hovered` | #946F00 | #F5CD47 | Hover state of warning.bold | | `color.background.warning.bold.pressed` | #533F04 | #E2B203 | Pressed state of warning.bold | ##### Text Colors Text colors ensure readability and hierarchy in content: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.text` | #172B4D | #C7D1DB | Primary text | | `color.text.subtle` | #44546F | #9FADBC | Secondary text | | `color.text.subtlest` | #626F86 | #738496 | Tertiary text | | `color.text.disabled` | #091E424F | #7384964F | Disabled text | | `color.text.inverse` | #FFFFFF | #1D2125 | Text on bold backgrounds | | `color.text.selected` | #0C66E4 | #85B8FF | Selected text | | `color.text.brand` | #0C66E4 | #85B8FF | Brand text | | `color.text.danger` | #CA3521 | #FF9C8F | Critical text | | `color.text.warning` | #B38600 | #E2B203 | Warning text | | `color.text.warning.inverse` | #172B4D | #C7D1DB | Warning text on bold backgrounds | | `color.text.success` | #1F845A | #4BCE97 | Success text | | `color.text.discovery` | #5E4DB2 | #B8ACF6 | Discovery text | | `color.text.information` | #0C66E4 | #85B8FF | Information text | ##### Icon Colors Icon colors maintain visual consistency with text colors: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.icon` | #44546F | #9FADBC | Default icons | | `color.icon.subtle` | #626F86 | #738496 | Subtle icons | | `color.icon.subtlest` | #626F86 | #738496 | Most subtle icons | | `color.icon.inverse` | #FFFFFF | #1D2125 | Icons on bold backgrounds | | `color.icon.disabled` | #091E424F | #7384964F | Disabled icons | | `color.icon.selected` | #0C66E4 | #85B8FF | Selected icons | | `color.icon.brand` | #0C66E4 | #85B8FF | Brand icons | | `color.icon.danger` | #CA3521 | #FF9C8F | Critical icons | | `color.icon.warning` | #B38600 | #E2B203 | Warning icons | | `color.icon.warning.inverse` | #172B4D | #C7D1DB | Warning icons on bold backgrounds | | `color.icon.success` | #1F845A | #4BCE97 | Success icons | | `color.icon.discovery` | #5E4DB2 | #B8ACF6 | Discovery icons | | `color.icon.information` | #0C66E4 | #85B8FF | Information icons | ##### Border Colors Border colors define component boundaries and states: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.border` | #091E4224 | #A1BDD914 | Default borders | | `color.border.bold` | #091E4240 | #A1BDD940 | Bold borders | | `color.border.brand` | #0C66E4 | #85B8FF | Brand borders | | `color.border.danger` | #CA3521 | #FF9C8F | Critical borders | | `color.border.disabled` | #091E420F | #A1BDD908 | Disabled borders | | `color.border.discovery` | #5E4DB2 | #B8ACF6 | Discovery borders | | `color.border.focused` | #0C66E4 | #85B8FF | Focused borders | | `color.border.information` | #0C66E4 | #85B8FF | Information borders | | `color.border.input` | #091E4224 | #A1BDD914 | Input borders | | `color.border.inverse` | #FFFFFF | #1D2125 | Borders on bold backgrounds | | `color.border.selected` | #0C66E4 | #85B8FF | Selected borders | | `color.border.success` | #1F845A | #4BCE97 | Success borders | | `color.border.warning` | #B38600 | #E2B203 | Warning borders | #### Typography Please prefer using the `Text` primitive or `Heading` component directly. ##### Font Font tokens control text appearance, size, and weight. Note: There are no font size tokens; font size can only be modified via the `font` shorthand property. ```tsx const styles = css({ font: token('font.body.small'), }); ``` | Token | Usage | |-|-| | `font.heading.xxlarge` | Brand promotions | | `font.heading.xlarge` | Brand promotions | | `font.heading.large` | Page titles | | `font.heading.medium` | Component headers | | `font.heading.small` | Small component headers | | `font.heading.xsmall` | Small component headers | | `font.heading.xxsmall` | Fine print headers | | `font.body.large` | Long-form text | | `font.body` | Default text | | `font.body.small` | Secondary content | | `font.code` | Code representation | ##### Font Weights Font weights control text emphasis: | Token | Value | Usage | |-|-|-| | `font.weight.regular` | 400 | Default text | | `font.weight.medium` | 500 | Text with icons | | `font.weight.semibold` | 600 | Emphasized text | | `font.weight.bold` | 700 | Strong emphasis | ##### Font Family Font family tokens define typefaces: | Token | Usage | |-|-| | `font.family.heading` | UI headings | | `font.family.body` | UI body text | | `font.family.code` | Code text | | `font.family.brand.heading` | Brand headings | | `font.family.brand.body` | Brand body text | #### Spacing Spacing tokens maintain consistent spacing. Base is `space.100` | Token | Value (px) | Value (rem) | Usage | |-|-|-|-| | `space.0` | 0px | 0rem | Reset spacing | | `space.025` | 2px | 0.125rem | Compact UI | | `space.050` | 4px | 0.25rem | Compact UI | | `space.075` | 6px | 0.375rem | Compact UI | | `space.100` | 8px | 0.5rem | Compact UI | | `space.150` | 12px | 0.75rem | Less dense UI | | `space.200` | 16px | 1rem | Less dense UI | | `space.250` | 20px | 1.25rem | Less dense UI | | `space.300` | 24px | 1.5rem | Less dense UI | | `space.400` | 32px | 2rem | Large UI | | `space.500` | 40px | 2.5rem | Large UI | | `space.600` | 48px | 3rem | Large UI | | `space.800` | 64px | 4rem | Largest UI | | `space.1000` | 80px | 5rem | Largest UI | ##### Negative Spacing Negative spacing tokens negate parent whitespace: | Token | Value (px) | Value (rem) | Usage | |-|-|-|-| | `space.negative.025` | -2px | -0.125rem | Small overlap | | `space.negative.050` | -4px | -0.25rem | Small overlap | | `space.negative.075` | -6px | -0.375rem | Small overlap | | `space.negative.100` | -8px | -0.5rem | Small overlap | | `space.negative.150` | -12px | -0.75rem | Large overlap | | `space.negative.200` | -16px | -1rem | Large overlap | | `space.negative.250` | -20px | -1.25rem | Large overlap | | `space.negative.300` | -24px | -1.5rem | Large overlap | | `space.negative.400` | -32px | -2rem | Largest overlap | #### Border Radius Border radius tokens define corner curvature. Base is `radius.small` | Token | Value (px) | Value (rem) | Usage | |-|-|-|-| | `radius.xsmall` | 2px | 0.125rem | Small containers such as badges | | `radius.small` | 4px | 0.25rem | Default radius, labels | | `radius.medium` | 6px | 0.375rem | Buttons and inputs | | `radius.large` | 8px | 0.5rem | Cards/small containers | | `radius.xlarge` | 12px | 0.75rem | Modals/large containers | | `radius.xxlarge` | 16px | 1rem | Largest containers (sparingly) | | `radius.full` | 9999px | 624.9375rem | Circular elements | #### Border Width Border width tokens define border thickness, often used with `color.border` tokens. Base is `border.width` ```tsx const styles = css({ border: `${token('border.width')} solid ${token('color.border')}`, }); ``` | Token | Value (px) | Value (rem) | Usage | |-|-|-|-| | `border.width` | 1px | 0.0625rem | Default width | | `border.width.selected` | 2px | 0.125rem | Selected elements | | `border.width.focused` | 2px | 0.125rem | Focus states | #### Elevation ##### Surface Elevation Surface elevation tokens define background layers: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `elevation.surface` | #FFFFFF | #1D2125 | Primary background | | `elevation.surface.hovered` | #F7F8F9 | #2C3338 | Hover state | | `elevation.surface.pressed` | #F7F8F9 | #2C3338 | Pressed state | | `elevation.surface.overlay` | #FFFFFF | #1D2125 | Overlay elements | | `elevation.surface.overlay.hovered` | #F7F8F9 | #2C3338 | Overlay hover state | | `elevation.surface.overlay.pressed` | #F7F8F9 | #2C3338 | Overlay pressed state | | `elevation.surface.raised` | #FFFFFF | #1D2125 | Movable elements | | `elevation.surface.raised.hovered` | #F7F8F9 | #2C3338 | Raised hover state | | `elevation.surface.raised.pressed` | #F7F8F9 | #2C3338 | Raised pressed state | | `elevation.surface.sunken` | #F7F8F9 | #2C3338 | Grouped elements | ##### Shadow Elevation Shadow elevation tokens define shadow styles: | Token | Usage | |-|-| | `elevation.shadow.overflow` | Scrolling content | | `elevation.shadow.overflow.perimeter` | Overflow fallback | | `elevation.shadow.overflow.spread` | Overflow fallback | | `elevation.shadow.overlay` | Overlay elements | | `elevation.shadow.raised` | Raised elements | #### Interaction States Interaction states define element responses: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.interaction.hovered` | #091E4208 | #A1BDD908 | Hover overlay | | `color.interaction.pressed` | #091E4214 | #A1BDD914 | Pressed overlay | | `color.interaction.inverse.hovered` | #FFFFFF14 | #FFFFFF14 | Inverse hover overlay | | `color.interaction.inverse.pressed` | #FFFFFF29 | #FFFFFF29 | Inverse pressed overlay | #### Skeleton States Skeleton states are for loading: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `color.skeleton` | #091E4208 | #A1BDD908 | Loading state | | `color.skeleton.subtle` | #091E4204 | #A1BDD904 | Loading effect | #### Opacity Opacity tokens control transparency: | Token | Light Value | Dark Value | Usage | |-|-|-|-| | `opacity.disabled` | 0.4 | 0.4 | Disabled state | | `opacity.loading` | 0.4 | 0.4 | Loading state | ### More Guidance #### Token Pairing You should match foreground and background color, eg. for dark background colors, we have a `token)'color.text.inverse')` to better achieve contrast ratios. ```tsx import { css } from '@atlaskit/css'; import { token } from '@atlaskit/tokens'; const styles = css({ backgroundColor: token('color.background.brand.bold'), color: token('color.text.inverse'), }); ``` #### Semantic Tokens Always prefer the semantically correct token name, even if the color doesn't match exactly. #### Dark Mode Support Never use hardcoded color values as they will break dark mode support. #### Interactive States Always provide clear visual feedback for interactive elements: ```tsx import { cssMap } from '@atlaskit/css'; import { token } from '@atlaskit/tokens'; const styles = cssMap({ button: { backgroundColor: token('color.background.brand.bold'), color: token('color.text.inverse'), '&:hover': { backgroundColor: token('color.background.brand.bold.hovered'), }, '&:focus': { outline: `2px solid ${token('color.border.focused')}`, outlineOffset: '2px', }, '&:active': { backgroundColor: token('color.background.brand.bold.pressed'), }, '&:disabled': { backgroundColor: token('color.background.disabled'), color: token('color.text.disabled'), } } }); ``` #### Focus Management Ensure proper focus indicators for keyboard navigation: ```tsx import { cssMap } from '@atlaskit/css'; import { token } from '@atlaskit/tokens'; const styles = cssMap({ focusable: { '&:focus-visible': { outline: `2px solid ${token('color.border.focused')}`, outlineOffset: '2px', }, '&:focus:not(:focus-visible)': { outline: 'none', } } }); ``` ## 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"` | Indicates the layout of the avatar group | | `avatar` | `AvatarComponent \| React.ElementType` | Component used to render each avatar | | `borderColor` | `string` | Typically the background color that the avatar is presented on | | `boundariesElement` | `"viewport" \| "window" \| "scrollParent"` | Element the overflow popup should be attached to | | `data` | `(AvatarPropTypes & { name: string; key?: string \| number; })[]` | An array of avatar prop data, that are spread onto each `avatar` component (required) | | `isTooltipDisabled` | `boolean` | Disables tooltips | | `label` | `string` | Text to be used as aria-label for the list of avatars | | `maxCount` | `number` | The maximum number of avatars allowed in the list | | `moreIndicatorLabel` | `string` | Text to be used as aria-label for the more indicator | | `onAvatarClick` | `(event: React.MouseEvent, analyticsEvent: AnalyticsEvent, index: number) => void` | Handle the click event on the avatar item | | `onMoreClick` | `(event: React.MouseEvent) => void` | Take control of the click event on the more indicator | | `overrides` | `AvatarGroupOverrides` | Custom overrides for the composed components | | `shouldPopupRenderToParent` | `boolean` | Determines whether the 'show more' popup has `shouldRenderToParent` applied | | `showMoreButtonProps` | `{ defaultChecked?: boolean; defaultValue?: string \| number \| readonly string[]; suppressContentEditableWarning?: boolean; suppressHydrationWarning?: boolean; accessKey?: string; autoCapitalize?: (string & {}) \| ... 5 more ... \| "characters"; ... 257 more ...; onTransitionEndCapture?: React.TransitionEventHandler<......` | Provide additional props to the MoreButton | | `size` | `"small" \| "medium" \| "large" \| "xlarge" \| "xxlarge"` | Defines the size of the avatar | | `tooltipPosition` | `"top" \| "bottom"` | Where the tooltip should appear relative to its target | ##### 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` | `"circle" \| "square" \| "hexagon"` | Indicates the shape of the avatar | | `aria-controls` | `string` | Identifies the popup element that the trigger controls | | `aria-expanded` | `boolean` | Announces to assistive technology whether the popup is currently open or closed | | `aria-haspopup` | `boolean \| "grid" \| "dialog" \| "menu" \| "listbox" \| "tree"` | Informs assistive technology that this element triggers a popup | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType>` | Replace the wrapping element | | `borderColor` | `string` | Used to override the default border color around the avatar body | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Supply a custom avatar component instead of the default | | `href` | `string` | Provides a url for avatars being used as a link | | `imgLoading` | `"lazy" \| "eager"` | Defines the loading behaviour of the avatar image | | `isDisabled` | `boolean` | Change the style to indicate the avatar is disabled | | `label` | `string` | Used to provide custom content to screen readers | | `name` | `string` | Provides alt text for the avatar image | | `onClick` | `(event: MouseEvent, analyticsEvent?: UIAnalyticsEvent) => void` | Handler to be called on click | | `presence` | `(string & {}) \| Presence \| Omit` | Indicates a user's online status by showing a small icon on the avatar | | `size` | `"small" \| "xxsmall" \| "UNSAFE_xsmall" \| "medium" \| "large" \| "xlarge" \| "xxlarge"` | | | `src` | `string` | A url to load an image from (this can also be a base64 encoded image) | | `stackIndex` | `number` | The index of where this avatar is in the group `stack` | | `status` | `(string & {}) \| Omit \| Status` | Indicates contextual information by showing a small icon on the avatar | | `tabIndex` | `number` | Assign specific tabIndex order to the underlying node | | `target` | `"_blank" \| "_self" \| "_top" \| "_parent"` | 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 ### @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" \| "successBold" \| "dangerBold" \| "warningBold" \| "discoveryBold"` | Affects the visual style of the badge | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | The value displayed within the badge | | `max` | `number \| false` | The maximum value to display | ##### 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` | `"warning" \| "error" \| "announcement"` | Visual style to be used for the banner | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Content to be shown next to the icon | | `icon` | `ReactElement>` | Icon to be shown left of the main content | ##### 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` | The children to be rendered within the blanket | | `isTinted` | `boolean` | Sets whether the blanket has a tinted background color | | `onBlanketClicked` | `(event: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void` | Handler function to be called when the blanket is clicked | | `shouldAllowClickThrough` | `boolean` | Whether mouse events can pass through the blanket | ##### 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` | The items to be included inside the Breadcrumbs wrapper | | `ellipsisLabel` | `string` | Text to be used as an accessible label for the ellipsis button that reveals collapsed breadcrumb items in a popup | | `label` | `string` | Text to be used as label of navigation region that wraps the breadcrumbs | | `size` | `"small" \| "medium"` | The size variant of the breadcrumbs | ##### 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) => void` | | | `aria-current` | `boolean \| "page"` | | | `aria-label` | `string` | Accessible label applied to the interactive breadcrumb control | | `aria-labelledby` | `string` | Accessible labelling relationship applied to the interactive breadcrumb control | | `elemBefore` | `string \| number \| ReactElement>` | An element to display before the breadcrumb | | `href` | `string` | The url or path which the breadcrumb should act as a link to | | `onClick` | `(event: MouseEvent) => void` | Handler to be called on click | | `onTooltipShown` | `() => void` | A function to be called when a truncated breadcrumb item's tooltip is shown | | `target` | `"" \| "_blank" \| "_self" \| "_top" \| "_parent"` | | | `text` | `string` | The text to appear within the breadcrumb as a link (required) | | `title` | `string` | Advisory text applied to the interactive breadcrumb control | | `truncationWidth` | `number` | The maximum width in pixels that an item can have before it is truncated | ##### 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` | The buttons to render inside the button group | | `label` | `string` | Refers to an `aria-label` attribute | | `titleId` | `string` | ID referenced by the button group wrapper's `aria-labelledby` attribute | ##### 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` | `"warning" \| "default" \| "primary" \| "discovery" \| "danger" \| "rovo" \| "subtle"` | The button style variation | | `autoFocus` | `boolean` | Set the button to autofocus on mount | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Text content to be rendered in the button (required) | | `iconAfter` | `ComponentClass \| Omit, any> \| FunctionComponent \| Omit<...>>` | Places an icon within the button, after the button's text | | `iconBefore` | `ComponentClass \| Omit, any> \| FunctionComponent \| Omit<...>>` | Places an icon within the button, before the button's text | | `isDisabled` | `boolean` | Disable the button to prevent user interaction | | `isLoading` | `boolean` | Conditionally show a spinner over the top of a button | | `isSelected` | `boolean` | Indicates that the button is selected | | `onBlur` | `(event: FocusEvent) => void` | Handler called on blur | | `onClick` | `(e: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void` | Handler called on click | | `onFocus` | `(event: FocusEvent) => void` | Handler called on focus | | `shouldFitContainer` | `boolean` | Option to fit button width to its parent width | | `spacing` | `"default" \| "compact"` | 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"` | The button style variation | | `autoFocus` | `boolean` | Set the button to autofocus on mount | | `icon` | `ComponentClass \| Omit, any> \| FunctionComponent \| Omit<...>>` | Places an icon within the button (required) | | `isDisabled` | `boolean` | Disable the button to prevent user interaction | | `isLoading` | `boolean` | Conditionally show a spinner over the top of a button | | `isSelected` | `boolean` | Indicates that the button is selected | | `isTooltipDisabled` | `boolean` | Prevents a tooltip with the label text from showing | | `label` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Provide an accessible label, often used by screen readers (required) | | `onBlur` | `(event: FocusEvent) => void` | Handler called on blur | | `onClick` | `(e: MouseEvent, analyticsEvent: UIAnalyticsEvent) => void` | Handler called on click | | `onFocus` | `(event: FocusEvent) => void` | Handler called on focus | | `shape` | `"circle" \| "default"` | Set the shape of the icon, defaults to square with rounded corners | | `spacing` | `"default" \| "compact"` | Controls the amount of padding in the button | | `tooltip` | `{ testId?: string; analyticsContext?: Record; content?: ReactNode \| (({ update }: { update?: () => void; }) => ReactNode); component?: ComponentType \| ForwardRefExoticComponent<...>; ... 16 more ...; shouldRenderToParent?: boolean; }` | 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` | `"default" \| "primary" \| "discovery" \| "rovo" \| "subtle"` | The button style variation | | `autoFocus` | `boolean` | Set the button to autofocus on mount | | `href` | `string \| RouterLinkConfig` | Provides a URL for link buttons (required) | | `icon` | `React.ComponentClass \| Omit, any> \| React.FunctionComponent \| Omit<...>>` | Places an icon within the button (required) | | `isDisabled` | `boolean` | Disable the button to prevent user interaction | | `isSelected` | `boolean` | Indicates that the button is selected | | `isTooltipDisabled` | `boolean` | Prevents a tooltip with the label text from showing | | `label` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Provide an accessible label, often used by screen readers (required) | | `newWindowLabel` | `string` | Override the default text used to announce that the link opens in a new window | | `onBlur` | `(event: React.FocusEvent) => void` | Handler called on blur | | `onClick` | `((e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void) & ((e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void)` | Handler called on click | | `onFocus` | `(event: React.FocusEvent) => void` | Handler called on focus | | `shape` | `"circle" \| "default"` | Set the shape of the icon, defaults to square with rounded corners | | `spacing` | `"default" \| "compact"` | Controls the amount of padding in the button | | `tooltip` | `{ testId?: string; analyticsContext?: Record; content?: React.ReactNode \| (({ update }: { update?: () => void; }) => React.ReactNode); component?: React.ComponentType \| React.ForwardRefExoticComponent<...>; ... 16 more ...; shouldRenderToParent?: boolean; }` | 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` | `"warning" \| "default" \| "primary" \| "discovery" \| "danger" \| "rovo" \| "subtle"` | The button style variation | | `autoFocus` | `boolean` | Set the button to autofocus on mount | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Text content to be rendered in the button (required) | | `href` | `string \| RouterLinkConfig` | Provides a URL for link buttons (required) | | `iconAfter` | `React.ComponentClass \| Omit, any> \| React.FunctionComponent \| Omit<...>>` | Places an icon within the button, after the button's text | | `iconBefore` | `React.ComponentClass \| Omit, any> \| React.FunctionComponent \| Omit<...>>` | Places an icon within the button, before the button's text | | `isDisabled` | `boolean` | Disable the button to prevent user interaction | | `isSelected` | `boolean` | Indicates that the button is selected | | `onBlur` | `(event: React.FocusEvent) => void` | Handler called on blur | | `onClick` | `(e: React.MouseEvent, analyticsEvent: UIAnalyticsEvent) => void` | Handler called on click | | `onFocus` | `(event: React.FocusEvent) => void` | Handler called on focus | | `shouldFitContainer` | `boolean` | Option to fit button width to its parent width | | `spacing` | `"default" \| "compact"` | 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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` | `"default" \| "primary"` | The style variation for child buttons | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Only two children are allowed (required) | | `isDisabled` | `boolean` | Whether all child buttons should be disabled | | `spacing` | `"default" \| "compact"` | 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` | The number of the day currently focused | | `defaultDay` | `number` | Sets the default value for `day` | | `defaultMonth` | `number` | Sets the default value for `month` | | `defaultPreviouslySelected` | `string[]` | Sets the default value for `previouslySelected` | | `defaultSelected` | `string[]` | Sets the default value for `selected` | | `defaultYear` | `number` | Sets the default value for `year` | | `disabled` | `string[]` | Takes an array of dates as string in the format 'YYYY-MM-DD' | | `disabledDateFilter` | `(date: string) => boolean` | A filter function that takes a date string in the format 'YYYY-MM-DD' and returns true if that date should be disabled | | `label` | `string` | The accessible label for the calendar | | `locale` | `string` | BCP 47 language tag (e | | `maxDate` | `string` | The latest enabled date | | `minDate` | `string` | The earliest enabled date | | `month` | `number` | The number of the month (from 1 to 12) which the calendar should be on | | `nextMonthLabel` | `string` | The aria-label attribute associated with the next month arrow, to describe it to assistive technology | | `onBlur` | `(event: FocusEvent) => void` | Function which is called when the calendar is no longer focused | | `onChange` | `(event: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void` | Called when the calendar is navigated | | `onFocus` | `(event: FocusEvent) => void` | Called when the calendar receives focus | | `onSelect` | `(event: SelectEvent, analyticsEvent: UIAnalyticsEvent) => void` | Function called when a day is clicked on | | `previouslySelected` | `string[]` | Takes an array of dates as string in the format 'YYYY-MM-DD' | | `previousMonthLabel` | `string` | The aria-label attribute associated with the previous month arrow, to describe it to assistive technology | | `selected` | `string[]` | Takes an array of dates as string in the format 'YYYY-MM-DD' | | `shouldSetFocusOnCurrentDay` | `boolean` | This allows the calendar to automatically set the focus to the current day | | `tabIndex` | `0 \| -1` | Indicates if the calendar can be focused by keyboard or only programmatically | | `today` | `string` | Value of current day, as a string in the format 'YYYY-MM-DD' | | `weekStartDay` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Start day of the week for the calendar | | `year` | `number` | 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` | Sets whether the checkbox begins as checked or unchecked | | `id` | `string` | The ID assigned to the input | | `isChecked` | `boolean` | Sets whether the checkbox is checked or unchecked | | `isDisabled` | `boolean` | Sets whether the checkbox is disabled | | `isIndeterminate` | `boolean` | Sets whether the checkbox is indeterminate | | `isInvalid` | `boolean` | Marks the field as invalid | | `isRequired` | `boolean` | Marks the field as required & changes the label style | | `label` | `string \| number \| ReactElement>` | The label to be displayed to the right of the checkbox | | `name` | `string` | The name of the submitted field in a checkbox | | `onChange` | `(e: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void` | Function that is called whenever the state of the checkbox changes | | `value` | `string \| number` | The value to be used in the checkbox input | | `xcss` | `false \| (XCSSValue<"alignItems", DesignTokenStyles, ""> & {} & XCSSPseudo<"alignItems", never, never, DesignTokenStyles> & XCSSMediaQuery<...> & { ...; } & { ...; })` | Bounded style API | ##### 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` | Content to be rendered in the inline code block | | `codeBidiWarningLabel` | `string` | Label for the bidi warning tooltip | | `hasBidiWarnings` | `boolean` | When set to `false`, disables code decorating with bidi warnings | | `isBidiWarningTooltipEnabled` | `boolean` | Sets whether to render tooltip with the warning or not | ##### 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` | Label for the bidi warning tooltip | | `firstLineNumber` | `number` | Sets the number of the first line, if showLineNumbers is set to true | | `hasBidiWarnings` | `boolean` | When set to `false`, disables code decorating with bidi warnings | | `highlight` | `string` | Comma delimited lines to highlight | | `highlightedEndText` | `string` | Screen reader text for the end of a highlighted line | | `highlightedStartText` | `string` | Screen reader text for the start of a highlighted line | | `isBidiWarningTooltipEnabled` | `boolean` | Sets whether to render tooltip with the warning or not | | `label` | `string` | Text used to describe that the content of the code block is scrollable | | `language` | `"html" \| "ruby" \| "text" \| "as" \| "css" \| "plaintext" \| "d" \| "r" \| "PHP" \| "php" \| "php3" \| "php4" \| "php5" \| "Java" \| "java" \| "CSharp" \| "csharp" \| "c#" \| "Python" \| "python" \| "py" \| ... 232 more ... \| "markdown"` | Language reference designed to be populated from `SUPPORTED_LANGUAGES` in `design-system/code` | | `shouldShowLineNumbers` | `boolean` | Sets whether to display code line numbers or not | | `shouldWrapLongLines` | `boolean` | Sets whether long lines will create a horizontally scrolling container | | `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[]` | A list of `CommentAction` items rendered as a row of buttons below the content | | `afterContent` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Content that is rendered after the comment's content | | `author` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | A `CommentAuthor` element containing the name of the author | | `avatar` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | The element to display as the avatar (required) | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Provide nested comments as children | | `content` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | The main content for the comment | | `edited` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | A `CommentEdited` element which displays next to the time | | `errorActions` | `React.ReactNode[]` | A list of `CommentAction` items rendered with a warning icon instead of the actions | | `errorIconLabel` | `string` | Text to show in the error icon label | | `headingLevel` | `"1" \| "3" \| "2" \| "4" \| "5" \| "6"` | Use this to set the semantic heading level of the comment | | `highlighted` | `boolean` | Sets whether this comment should be highlighted | | `id` | `string` | An ID to be applied to the comment | | `isError` | `boolean` | Indicates whether the component is in an error state | | `isSaving` | `boolean` | Enables "optimistic saving" mode which removes actions and displays text from the `savingText` prop | | `restrictedTo` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Text for the "restricted to" label | | `savingText` | `string` | Text to show when in "optimistic saving" mode | | `shouldHeaderWrap` | `boolean` | Controls if the comment header should wrap | | `shouldRenderNestedCommentsInline` | `boolean` | Controls if nested comments are rendered at the same depth as the parent comment | | `time` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | A `CommentTime` element containing the time to display | | `type` | `string` | The type of comment | ##### 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` | `"warning" \| "danger" \| "neutral"` | Controls the visual style of the date label | | `hasIconBefore` | `boolean` | When `true`, an icon is displayed before the label text | | `iconLabel` | `string` | The accessible label for the icon | | `isSpacious` | `boolean` | When `true`, increases the padding and height of the date label for use in more spacious layouts (e | | `label` | `string` | The text content to display inside the date label (required) | | `maxWidth` | `string \| number` | The maximum width of the date label | ##### 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` | `"warning" \| "danger" \| "neutral"` | Controls the visual style of the trigger | | `aria-controls` | `string` | Identifies the popup element that this trigger controls | | `aria-expanded` | `boolean` | Announces to assistive technology whether the popup is currently open | | `aria-haspopup` | `boolean \| "dialog"` | Informs assistive technology that this element triggers a popup | | `aria-label` | `string` | Defines a string value that labels the trigger element for assistive technology | | `hasIconBefore` | `boolean` | When `true`, an icon is displayed before the label text | | `iconLabel` | `string` | The accessible label for the leading icon | | `isLoading` | `boolean` | 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` | When `true`, renders the trigger in a selected/active state using the pressed background colour for the current appearance | | `isSpacious` | `boolean` | 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 (required) | | `maxWidth` | `string \| number` | The maximum width of the trigger | | `onClick` | `(event: React.MouseEvent) => void` | 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` | Used to associate accessible descriptions to the date picker | | `autoFocus` | `boolean` | Set the picker to autofocus on mount | | `calendarLabel` | `string` | The aria-label attribute associated with the calendar | | `clearControlLabel` | `string` | Set the `aria-label` for the clear button | | `dateFormat` | `string` | Format the date with a string that is accepted by [date-fns's format function](https://date-fns | | `defaultValue` | `string` | The default for `value` | | `disabled` | `string[]` | An array of ISO dates that should be disabled on the calendar | | `disabledDateFilter` | `(date: string) => boolean` | A filter function for disabling dates on the calendar | | `formatDisplayLabel` | `(value: string, dateFormat: string) => string` | A function for formatting the date displayed in the input | | `id` | `string` | Set the id of the field | | `inputLabel` | `string` | The name of the input, used when `shouldShowCalendarButton` is true | | `inputLabelId` | `string` | The ID of the label for the input, used when `shouldShowCalendarButton` is true | | `isDisabled` | `boolean` | Set if the picker is disabled | | `isInvalid` | `boolean` | Set if the picker has an invalid value | | `isOpen` | `boolean` | Set if the picker is open | | `isRequired` | `boolean` | Set the field as required | | `label` | `string` | Accessible name for the Date Picker Select, rendered as `aria-label` | | `locale` | `string` | Locale used to format the date and calendar | | `maxDate` | `string` | The latest enabled date | | `minDate` | `string` | The earliest enabled date | | `name` | `string` | The name of the field | | `nextMonthLabel` | `string` | The aria-label attribute associated with the next-month arrow | | `onBlur` | `(event: FocusEvent) => void` | Called when the field is blurred | | `onChange` | `(value: string) => void` | Called when the value changes | | `onFocus` | `(event: FocusEvent) => void` | Called when the field is focused | | `openCalendarLabel` | `string` | The label associated with the button to open the calendar, rendered via the `shouldShowCalendarButton` prop | | `parseInputValue` | `(date: string, dateFormat: string) => Date` | A function for parsing input characters and transforming them into a Date object | | `placeholder` | `string` | Placeholder text displayed in input | | `previousMonthLabel` | `string` | The aria-label attribute associated with the previous-month arrow | | `selectProps` | `Omit, "aria-describedby" \| "aria-label" \| "placeholder" \| "inputId"> & { 'aria-describedby'?: never; 'aria-label'?: never; inputId?: never; placeholder?: never; } & { ...; }` | | | `shouldShowCalendarButton` | `boolean` | Provides a functional calendar button that opens the calendar picker that lives on the right side of the date picker | | `spacing` | `"default" \| "compact"` | The spacing for the select control | | `value` | `string` | The ISO time used as the input value | | `weekStartDay` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Start day of the week for the calendar | ##### 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` | Used to associate accessible descriptions to both the date and time picker | | `autoFocus` | `boolean` | Set the picker to autofocus on mount | | `clearControlLabel` | `string` | Set the `aria-label` for the clear button | | `datePickerProps` | `DatePickerBaseProps` | Props applied to the `DatePicker` | | `defaultValue` | `string` | The default for `value` | | `id` | `string` | Set the id of the field | | `isDisabled` | `boolean` | Set if the field is disabled | | `isInvalid` | `boolean` | Set if the picker has an invalid value | | `isRequired` | `boolean` | Set the field as required | | `locale` | `string` | Locale used for formatting dates and times | | `name` | `string` | The name of the field | | `onBlur` | `(event: FocusEvent) => void` | Called when the field is blurred | | `onChange` | `(value: string) => void` | Called when the value changes and the date / time is a complete value, or empty | | `onFocus` | `(event: FocusEvent) => void` | Called when the field is focused | | `parseValue` | `(dateTimeValue: string, date: string, time: string, timezone: string) => { dateValue: string; timeValue: string; zoneValue: string; }` | Function used to parse datetime values into their date, time and timezone sub-values | | `spacing` | `"default" \| "compact"` | The spacing for the select control | | `timePickerProps` | `TimePickerBaseProps` | Props applied to the `TimePicker` | | `value` | `string` | 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` | Used to associate accessible descriptions to the time picker | | `autoFocus` | `boolean` | Set the picker to autofocus on mount | | `clearControlLabel` | `string` | Set the `aria-label` for the clear button | | `defaultValue` | `string` | The default for `value` | | `formatDisplayLabel` | `(time: string, timeFormat: string) => string` | A function for formatting the displayed time value in the input | | `hideIcon` | `boolean` | Hides icon for dropdown indicator | | `id` | `string` | Set the id of the field | | `isDisabled` | `boolean` | Set if the field is disabled | | `isInvalid` | `boolean` | Set if the picker has an invalid value | | `isOpen` | `boolean` | Set if the dropdown is open | | `isRequired` | `boolean` | Set the field as required | | `label` | `string` | Accessible name for the Time Picker Select, rendered as `aria-label` | | `locale` | `string` | Locale used to format the time | | `name` | `string` | The name of the field | | `onBlur` | `(event: FocusEvent) => void` | Called when the field is blurred | | `onChange` | `(value: string) => void` | Called when the value changes | | `onFocus` | `(event: FocusEvent) => void` | Called when the field is focused | | `openTimeLabel` | `string` | The accessible label for the button that opens the time picker | | `parseInputValue` | `(time: string, timeFormat: string) => string \| Date` | A function for parsing input characters and transforming them into either a string or a Date object | | `placeholder` | `string` | Placeholder text displayed in input | | `selectProps` | `Omit, "aria-describedby" \| "aria-label" \| "placeholder" \| "inputId"> & { 'aria-describedby'?: never; 'aria-label'?: never; inputId?: never; placeholder?: never; }` | | | `shouldShowTimeButton` | `boolean` | Provides a functional clock button that opens the time picker | | `spacing` | `"default" \| "compact"` | The spacing for the select control | | `timeFormat` | `string` | Format the time with a string that is accepted by [date-fns's format function](https://date-fns | | `timeIsEditable` | `boolean` | Set if users can edit the input, allowing them to add custom times | | `times` | `string[]` | The times shown in the dropdown | | `value` | `string` | 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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 | |-|-|-| | `aria-haspopup` | `boolean \| "grid" \| "dialog" \| "menu" \| "listbox" \| "tree"` | An optional boolean value used to indicate if the dropdown item has popup or not | | `children` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Primary content for the item (required) | | `component` | `ComponentClass, any> \| FunctionComponent>` | Custom component to render as an item | | `description` | `string \| global.JSX.Element` | Description of the item | | `elemAfter` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Element to render after the item text | | `elemBefore` | `string \| number \| boolean \| ReactElement> \| Iterable \| ReactPortal` | Element to render before the item text | | `href` | `string` | Link to another page | | `isDisabled` | `boolean` | Makes the element appear disabled | | `isSelected` | `boolean` | Makes the element appear selected | | `onClick` | `(e: MouseEvent \| KeyboardEvent) => void` | Event that is triggered when the element is clicked | | `rel` | `string` | The relationship of the linked URL as space-separated link types | | `returnFocusRef` | `RefObject` | If ref is passed, focus returns to that specific ref element after dropdown item clicked | | `role` | `string` | An optional string value that specifies the role of the dropdown item | | `shouldDescriptionWrap` | `boolean` | When `true` the description of the item will wrap multiple lines if it exceeds the width of the dropdown menu | | `shouldTitleWrap` | `boolean` | When `true` the title of the item will wrap multiple lines if it exceeds the width of the dropdown menu | | `target` | `string` | Where to display the linked URL, see [anchor information](https://developer | | `title` | `string` | 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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` | Children of the section (required) | | `hasSeparator` | `boolean` | Use this to render a border at the top of the section | | `id` | `string` | Unique identifier for the element | | `isList` | `boolean` | If your menu contains a list, use this to add `
    ` and `
  • ` tags around the items | | `isScrollable` | `boolean` | Enables scrolling within the section | | `label` | `string` | Provide an accessible label for the section via `aria-label` for assistive technology | | `title` | `string` | The text passed into the internal `HeadingItem` | | `titleId` | `string` | ID referenced by the menu group wrapper's `aria-labelledby` attribute | ##### 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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` | Primary content for the item (required) | | `defaultSelected` | `boolean` | Sets whether the checkbox begins selected | | `description` | `string \| JSX.Element` | Description of the item | | `id` | `string` | Unique id of a checkbox (required) | | `isDisabled` | `boolean` | Makes the checkbox appear disabled as well as removing interactivity | | `isSelected` | `boolean` | Sets whether the checkbox is checked or unchecked | | `onClick` | `(e: React.MouseEvent \| React.KeyboardEvent) => void` | Event that is triggered when the checkbox is clicked | | `shouldDescriptionWrap` | `boolean` | When `true` the description of the item will wrap multiple lines if it's long enough | | `shouldTitleWrap` | `boolean` | When `true` the title of the item will wrap multiple lines if it's long enough | | `title` | `string` | 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` | Children of the section (required) | | `hasSeparator` | `boolean` | Use this to render a border at the top of the section | | `id` | `string` | Unique identifier for the checkbox group (required) | | `isList` | `boolean` | If your menu contains a list, use this to add `
      ` and `
    • ` tags around the items | | `isScrollable` | `boolean` | Enables scrolling within the section | | `label` | `string` | Provide an accessible label for the section via `aria-label` for assistive technology | | `title` | `string` | The text passed into the internal `HeadingItem` | | `titleId` | `string` | ID referenced by the menu group wrapper's `aria-labelledby` attribute | ##### 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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` | Primary content for the item (required) | | `defaultSelected` | `boolean` | Sets whether the checkbox begins selected | | `description` | `string \| JSX.Element` | Description of the item | | `id` | `string` | Unique ID of the checkbox (required) | | `isDisabled` | `boolean` | Makes the checkbox appear disabled as well as removing interactivity | | `isSelected` | `boolean` | Sets whether the checkbox is checked or unchecked | | `onClick` | `(e: React.MouseEvent \| React.KeyboardEvent) => void` | Event that is triggered when the checkbox is clicked | | `shouldDescriptionWrap` | `boolean` | When `true` the description of the item will wrap multiple lines if it's long enough | | `shouldTitleWrap` | `boolean` | When `true` the title of the item will wrap multiple lines if it's long enough | | `title` | `string` | 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` | Children of the section (required) | | `hasSeparator` | `boolean` | Use this to render a border at the top of the section | | `id` | `string` | (required) | | `isList` | `boolean` | If your menu contains a list, use this to add `
        ` and `
      • ` tags around the items | | `isScrollable` | `boolean` | Enables scrolling within the section | | `label` | `string` | Provide an accessible label for the section via `aria-label` for assistive technology | | `title` | `string` | The text passed into the internal `HeadingItem` | | `titleId` | `string` | ID referenced by the menu group wrapper's `aria-labelledby` attribute | ##### 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 DropdownMenu from '@atlaskit/dropdown-menu/dropdown-menu'; import DropdownItem from '@atlaskit/dropdown-menu/dropdown-menu-item'; import DropdownItemGroup from '@atlaskit/dropdown-menu/dropdown-menu-item-group'; 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"` | Controls the appearance of the menu | | `autoFocus` | `boolean` | Controls if the first menu item receives focus when menu is opened | | `children` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Content that will be rendered inside the layer element | | `defaultOpen` | `boolean` | Controls the initial open state of the dropdown | | `isLoading` | `boolean` | If true, a spinner is rendered instead of the items | | `isOpen` | `boolean` | Controls the open state of the dropdown | | `label` | `string` | Provide an accessible label via `aria-label` for assistive technology | | `menuLabel` | `string` | Provide an accessible label for the menu element for assistive technology | | `onOpenChange` | `(args: OnOpenChangeArgs) => void` | Called when the menu should be open/closed | | `placement` | `"auto" \| "auto-start" \| "auto-end" \| "top" \| "bottom" \| "right" \| "left" \| "top-start" \| "top-end" \| "bottom-start" \| "bottom-end" \| "right-start" \| "right-end" \| "left-start" \| "left-end"` | Position of the menu | | `returnFocusRef` | `React.RefObject` | If ref is passed, focus returns to that specific ref element after dropdown dismissed | | `shouldFitContainer` | `boolean` | This fits the dropdown menu width to its parent's width | | `shouldIgnoreCloseEvent` | `(event: Event \| React.MouseEvent \| React.KeyboardEvent) => boolean` | 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"` | Controls the spacing density of the menu | | `statusLabel` | `string` | Text to be used as status for assistive technologies | | `trigger` | `string \| ((triggerButtonProps: CustomTriggerProps) => React.ReactElement>)` | Content that triggers the dropdown menu to open and close | ##### 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` | Caption for the table styled as a heading | | `defaultPage` | `number` | When the table is initially rendered, use this to set which page number is shown by default | | `defaultSortKey` | `string` | Sets which column the rows should be sorted by when the table is initially rendered | | `defaultSortOrder` | `"ASC" \| "DESC"` | Default column sort order used when initially rendering | | `emptyView` | `ReactElement>` | Shown when the table has no content | | `head` | `HeadType` | Cells to be placed in the head of the table | | `highlightedRowIndex` | `number \| number[]` | Use this to set if the row will be highlighted | | `isFixedSize` | `boolean` | Use this to force columns to use their initial width regardless of the size of the content that loads in | | `isLoading` | `boolean` | Displays a loading spinner overlaid on top of the current page | | `isRankable` | `boolean` | Use this to enable drag and drop sorting of table rows | | `isRankingDisabled` | `boolean` | Disables being able to drop rows on the table | | `label` | `string` | If you don’t use a caption, then you’ll need to use label to describe the table for assistive technologies | | `loadingLabel` | `string` | Use this to set a label for assistive technology that describes the loading state | | `loadingSpinnerSize` | `"small" \| "large"` | Configuration of the loading spinner shown when `isLoading` is true | | `onPageRowsUpdate` | `(pageRows: RowType[]) => void` | A callback that happens when the rows displayed on a page have changed | | `onRankEnd` | `(rankEnd: RankEnd) => void` | A callback that happens when a drop of a row has completed | | `onRankStart` | `(rankStart: RankStart) => void` | A callback that happens when a drag of a row has started | | `onSetPage` | `(page: number, UIAnalyticsEvent?: UIAnalyticsEvent) => void` | A callback that happens when the table page has changed | | `onSort` | `(data: any, UIAnalyticsEvent?: UIAnalyticsEvent) => void` | A callback that happens when a column heading has been sorted | | `page` | `number` | Page the table should show | | `paginationi18n` | `I18nShape` | Labels for the previous and next buttons used in pagination | | `rows` | `RowType[]` | Rows to be placed in the table | | `rowsPerPage` | `number` | Use this to control how many rows should be displayed per page | | `sortKey` | `string` | Column key that the rows should be sorted by | | `sortOrder` | `"ASC" \| "DESC"` | 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` | Caption for the table styled as a heading | | `emptyView` | `React.ReactElement>` | Shown when the table has no content | | `head` | `HeadType` | Cells to be placed in the head of the table | | `highlightedRowIndex` | `number \| number[]` | Use this to set which rows will be highlighted | | `isFixedSize` | `boolean` | Use this to force columns to use their initial width regardless of the size of the content that loads in | | `isLoading` | `boolean` | Displays a loading spinner overlaid on top of the current page | | `isRankable` | `boolean` | Use this to enable drag and drop sorting of table rows | | `isRankingDisabled` | `boolean` | Disables being able to drop rows on the table | | `label` | `string` | If you don’t use a caption, then you’ll need to use label to describe the table for assistive technologies | | `loadingLabel` | `string` | Accessible name for loading states spinner | | `loadingSpinnerSize` | `"small" \| "large"` | Sets the size of the loading spinner when `isLoading` is true | | `onPageRowsUpdate` | `(pageRows: RowType[]) => void` | A callback that happens when the rows displayed on a page have changed | | `onRankEnd` | `(rankEnd: RankEnd, uiAnalyticsEvent?: UIAnalyticsEvent) => void` | A callback that happens when a drop of a row has completed | | `onRankStart` | `(rankStart: RankStart) => void` | A callback that happens when a drag of a row has started | | `onSetPage` | `(page: number, UIAnalyticsEvent?: UIAnalyticsEvent) => void` | A callback that happens when the table page has changed | | `onSort` | `(data: any, UIAnalyticsEvent?: UIAnalyticsEvent) => void` | A callback that happens when a column heading has been sorted | | `page` | `number` | Page the table should show | | `paginationi18n` | `I18nShape` | Labels for the pagination wrapper, previous and next buttons used in pagination | | `rows` | `RowType[]` | Rows to be placed in the table | | `rowsPerPage` | `number` | Controls how many rows should be displayed per page | | `sortKey` | `string` | Column key that the rows should be sorted by | | `sortOrder` | `"ASC" \| "DESC"` | Column sort order | | `totalRows` | `number` | 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` | Accessible name for the action buttons group of empty state | | `description` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | The main block of text that holds additional supporting information | | `header` | `string` | Title that briefly describes the page to the user (required) | | `headingLevel` | `number` | The value used to set the heading level of the header element | | `headingSize` | `"xsmall" \| "medium"` | The keyword used to set the visual appearance of the header element | | `imageHeight` | `number` | Height of the image that is rendered in EmptyState component | | `imageUrl` | `string` | The url of image that will be shown above the title, fed directly into the `src` prop of an element | | `imageWidth` | `number` | Width of the image that is rendered in EmptyState component | | `isLoading` | `boolean` | Used to indicate a loading state | | `maxImageHeight` | `number` | Maximum height (in pixels) of the image, default value is 160 | | `maxImageWidth` | `number` | Maximum width (in pixels) of the image, default value is 160 | | `primaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Primary action button for the page, usually it will be something like "Create" (or "Retry" for error pages) | | `renderImage` | `(props: RenderImageProps) => React.ReactNode` | An alternative API to supply an image using a render prop | | `secondaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Secondary action button for the page | | `tertiaryAction` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | Button with link to some external resource like documentation or tutorial, it will be opened in a new tab | | `width` | `"narrow" \| "wide"` | Controls how much horizontal space the component fills | ##### 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` | `ActionType[]` | Array of clickable actions to be shown at the bottom of the flag | | `appearance` | `"warning" \| "success" \| "error" \| "normal" \| "info"` | Makes the flag appearance bold | | `autoDismissSeconds` | `number` | Duration in seconds before flag gets auto dismissed | | `delayAnnouncement` | `number` | Milliseconds to delay the screen reader announcement due to announcement conflict | | `description` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | The secondary content shown below the flag title | | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Specifies the heading level in the document structure | | `icon` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | The icon displayed in the top-left of the flag | | `id` | `string \| number` | A unique identifier used for rendering and onDismissed callbacks (required) | | `linkComponent` | `React.ComponentClass \| React.FunctionComponent` | A link component that is passed down to the `@atlaskit/button` used by actions, to allow custom routers to be used | | `onBlur` | `(e: React.FocusEvent, analyticsEvent: UIAnalyticsEvent) => void` | Standard onBlur event, applied to Flag by AutoDismissFlag | | `onDismissed` | `(id: string \| number, analyticsEvent: UIAnalyticsEvent) => void` | Handler which will be called when a Flag's dismiss button is clicked | | `onFocus` | `(e: React.FocusEvent, analyticsEvent: UIAnalyticsEvent) => void` | Standard onFocus event, applied to Flag by AutoDismissFlag | | `onMouseOut` | `(event: React.MouseEvent) => void` | Standard onMouseOut event, applied to Flag by AutoDismissFlag | | `onMouseOver` | `(event: React.MouseEvent) => void` | Standard onMouseOver event, applied to Flag by AutoDismissFlag | | `title` | `string \| number \| boolean \| React.ReactElement> \| Iterable \| React.ReactPortal` | 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 */}