# Components
> This section offers a comprehensive list of components along with best practices to guide their effective usage.
## Component List
A list of all the components available in the design system.
### Layout
| Component Name | Description |
| -------------- | -------------------------------------------------------------------------------- |
| `Flex` | A flex component is used to create a flex container. |
| `Grid` | The grid component is used to create a grid container. |
| `Inline` | An inline component is a layout primitive used to arrange elements horizontally. |
| `Stack` | A stack component is a layout primitive used to arrange elements vertically. |
### Buttons
| Component Name | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Button` | A button allows a user to initiate an action. |
| `ButtonGroup` | A button group handles the spacing and orientation for a grouping of buttons. |
| `LinkButton` | A LinkButton looks like a button but behaves like a link. |
| `SegmentedControl` | The SegmentedControl component presents a horizontal row of options or actions that are contextually or conceptually related. It allows users to select a single option at a time. |
| `Tile` | A tile groups information into an interactive element to let users browse and take action on a group of related items. |
| `TileGroup` | A TileGroup groups Tiles to let users browse and take action on a group of related items. |
| `ToggleButton` | Offer a similar experience as a checkbox or radio with the appearance of a button. |
### Collections
| Component Name | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ListBox` | A listbox is a list of interactive options that appears when users interact with an element or perform a specific action. |
| `Menu` | A menu offers a list of choices to the user, such as a set of actions or functions. |
| `TagGroup` | The TagGroup is a dynamic UI component that encapsulates a collection of tags. Each tag represents a label, category, keyword, or filter, and can be used for various groupings |
| `Tag` | A tag represents a label, category, keyword, or filter, and can be used for various groupings. If you need multiple tags, consider using the TagGroup component. |
### Date and time
| Component Name | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `Calendar` | A calendar displays one or more date grids and allows users to select a single date. |
| `DatePicker` | A date picker allows users to select a single date from a calendar. |
| `DateRangePicker` | A date range picker allows users to select a range of dates from a calendar. |
| `RangeCalendar` | A range calendar displays one or more date grids and allows users to select a contiguous range of dates. |
### Forms
| Component Name | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Checkbox` | Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections. |
| `CheckboxGroup` | A checkbox group handles the spacing and orientation for a grouping of checkboxes, as well as providing a label. |
| `Form` | Forms are used to gather information from the user. |
| `NumberField` | A number field is a specialized input that allows a user to enter a number. |
| `PasswordField` | A password field is a specialized text field that allows a user to enter a password. |
| `RadioGroup` | A radio group is used to group related options together. |
| `SearchField` | A search field is a specialized text input allowing the user to perform a search. |
| `Switch` | A switch is used to quickly switch between two possible states. |
| `TextArea` | A text area serves as a multi-line, plain-text editing interface. |
| `TextField` | A text field allows a user to enter a plain text value. |
### Icons
| Component Name | Description |
| -------------- | ----------------------------------------------------------- |
| `Icon` | An icon component is used to render a custom icon. |
| `IconList` | An IconList encapsulates a collection of icons. |
| `RichIcon` | A rich icon component is used to render a rich custom icon. |
### Navigation
| Component Name | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Accordion` | An Accordion is a grouping of related disclosures. It supports both single and multiple expanded items. |
| `Disclosure` | The disclosure component is used to put long sections of information under a block that users can expand or collapse. |
| `Link` | A link allows a user to navigate to a different location. |
| `Tabs` | Tabs are used to organize content by grouping similar information on the same page. |
### Overlays
| Component Name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Alert` | An Alert is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow. |
| `ContextualHelp` | Contextual help shows a user extra information about the state of an adjacent component. It explains a high-level topic about an experience and can point users to more information elsewhere. |
| `Modal` | Modals focus the user's attention exclusively on one task or piece of information via a window that sits on top of the page content. |
| `Popover` | A popover displays additional content when a user interacts with a trigger element. |
| `Tooltip` | Tooltips display additional information upon hover or focus that is contextual, helpful, and nonessential while providing the ability to communicate and give clarity to a user. |
### Pickers
| Component Name | Description |
| -------------- | --------------------------------------------------------------------------------------------------- |
| `ComboBox` | A combo box allows the user to make a selection from a list of suggested, likely or desired values. |
| `Select` | A select displays a collapsible list of options from which the user can select one. |
### Status
| Component Name | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Badge` | A badge is used to bring attention to an element. |
| `Callout` | A Callout informs users about important changes or persistent conditions. Use this component to communicate to users in a prominent way. Callouts are placed at the top of the page or section they apply to, and below the page or section header. |
| `CompactCallout` | A CompactCallout informs users about important changes or persistent conditions. Use this component to communicate to users in a prominent way. Callouts are placed at the top of the page or section they apply to, and below the page or section header. |
| `FloatingBadge` | A floating badge allows the user to position a badge relative to another component. |
| `Spinner` | A spinner indicates that a part of the product is currently performing a task of unknown duration. |
### Content
| Component Name | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Avatar` | Avatars are used to represent a user, a team or another entity in the Workleap ecosystem. They are often paired with text where room is available. |
| `Card` | Cards are used to group similar concepts and tasks to make it easier for users to scan, read and get things done. |
| `Divider` | A divider separates sections of content or groups. |
| `Heading` | A heading is a primitive component matching Hopper's typography type scale. |
| `IllustratedMessage` | An illustrated message display an image and a message, usually for an empty state or an error page. |
| `Illustration` | An illustration compose an image with a background color. Use an illustration as an hero in a modal. |
| `Image` | An image component that can be used to display images. |
| `Label` | A label is a primitive component matching Hopper's typography type scale. |
| `Paragraph` | A paragraph is used to render blocks of text. |
| `Text` | A text component is a primitive component matching Hopper's typography type scale. |
### Placeholders
| Component Name | Description |
| -------------- | ---------------------------------------------------------- |
| `Content` | A placeholder for the main content section of a component. |
| `Footer` | A placeholder for a footer section. |
| `Header` | A placeholder for an header section. |
### Html elements
| Component Name | Description |
| -------------- | -------------------------------------------------------------- |
| `A` | A specialized component to represent an HTML anchor element. |
| `Address` | A specialized component to represent an HTML address element. |
| `Article` | A specialized component to represent an HTML article element. |
| `Aside` | A specialized component to represent an HTML aside element. |
| `Div` | A specialized component to represent an HTML div element. |
| `HtmlButton` | A specialized button component for HTML button element. |
| `HtmlFooter` | A specialized component to represent an HTML footer element. |
| `HtmlHeader` | A specialized component to represent an HTML header element. |
| `HtmlInput` | A specialized component to represent an HTML input element. |
| `HtmlSection` | A specialized component to represent an HTML section element. |
| `Img` | A specialized component to represent an HTML img element. |
| `Main` | A specialized component to represent an HTML main element. |
| `Nav` | A specialized component to represent an HTML nav element. |
| `Span` | A specialized component to represent an HTML span element. |
| `Table` | A specialized component to represent an HTML table element. |
| `UL` | A specialized component to represent an HTML ul/ol/li element. |
### Building blocks
| Component Name | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Box` | A flexible container component that can render as any HTML element or React component. Supports all styled system props for consistent spacing, layout, and styling. |
| `ErrorMessage` | An error message displays validation errors for a form field. |
| `HelperMessage` | A helper message component displays auxiliary text to guide users in the interface. |
| `PopoverBase` | A simple React Aria Popover with hopper's styling |
## A
A specialized component to represent an HTML anchor element.
```tsx
import { A } from "@hopper-ui/components";
export default function Example() {
return (
Futurama
);
}
```
### Usage
An anchor component accepts all the [anchor HTML element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a) and [Hopper styled component props](/styled-system/concepts/styling.md).
## Accordion
An Accordion is a grouping of related disclosures. It supports both single and multiple expanded items.
* Source:
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
### Anatomy
#### Structure
```tsx
/* (Required) A disclosure for the Accordion */
/* (Required) A header for the Disclosure */
/* (Optional) A text description for the DisclosureHeader */
/* (Optional) An icon for the DisclosureHeader */
/* (Required) A panel for the Disclosure */
```
#### Composed Components
An `Accordion` uses the following components.
| Component | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------- |
| Disclosure | The disclosure component is used to put long sections of information under a block that users can expand or collapse. |
| Icon | An icon component is used to render a custom icon. |
| Text | A text component is a primitive component matching Hopper's typography type scale. |
### Usage
#### Disabled
An accordion can be disabled.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
#### Variants
An accordion has multiple variants.
**Standalone** - Used when the accordion is not inside a container.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
**Inline** - Used when placing a accordion inside a container.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
#### Expanded
By default, only one disclosure will be expanded at a time. Use `allowsMultipleExpanded` prop to expand multiple disclosures.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
#### Icon
An accordion heading can contain an icon.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div, Text } from "@hopper-ui/components";
import { PinSolidIcon, SparklesIcon, SproutIcon } from "@hopper-ui/icons";
export default function Example() {
return (
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
#### Description
An accordion heading can contain a description.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div, Inline, Text } from "@hopper-ui/components";
export default function Example() {
return (
Workleap OfficevibeEngagement survey and feedbackHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardInteractive org chart and directoryMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformancePerformance review management and trackingDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
#### Controlled
An accordion can handle its opened panels in controlled mode.
```tsx
import { Accordion, Disclosure, DisclosureHeader, DisclosurePanel, Div, Span } from "@hopper-ui/components";
import { useState } from "react";
export default function Example() {
const [expandedKeys, setExpandedKeys] = useState>(new Set());
const handleExpandedChange = (keys: Set) => {
setExpandedKeys(keys);
};
return (
{expandedKeys.size > 0 ? `${Array.from(expandedKeys).join(", ")} is opened.` : "No sections are opened."}
Workleap OfficevibeHelp employees speak up and make sure they feel heard. Continuous and real-time surveys offer feedback to celebrate every win, recognize commitment, and uncover challenges.Workleap PingboardMake teamwork work. Use your org chart to create lasting connections across your distributed and hybrid teams to make collaboration easier.Workleap PerformanceDrive impact by simplifying how your leaders and you manage team performance throughout the year.
);
}
```
### Props
| Prop | Type | Default | Description |
| ---------------------- | ------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| variant | `"standalone" \| "inline"` | | |
| style | `StyleOrFunction` | | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| allowsMultipleExpanded | `boolean` | | Whether multiple items can be expanded at the same time. |
| isDisabled | `boolean` | | Whether all items are disabled. |
| expandedKeys | `Iterable` | | The currently expanded keys in the group (controlled). |
| defaultExpandedKeys | `Iterable` | | The initial expanded keys in the group (uncontrolled). |
| children | `ChildrenOrFunction` | | The children of the component. A function may be provided to alter the children based on component state. |
| className | `ClassNameOrFunction` | | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| dir | `string` | | |
| lang | `string` | | |
| inert | `boolean` | | |
| translate | `"yes" \| "no"` | | |
##### Events
| Prop | Type | Default | Description |
| --------------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
| onExpandedChange | `((keys: Set) => any)` | | Handler that is called when items are expanded or collapsed. |
| onClick | `MouseEventHandler` | | |
| onClickCapture | `MouseEventHandler` | | |
| onAuxClick | `MouseEventHandler` | | |
| onAuxClickCapture | `MouseEventHandler` | | |
| onContextMenu | `MouseEventHandler` | | |
| onContextMenuCapture | `MouseEventHandler` | | |
| onDoubleClick | `MouseEventHandler` | | |
| onDoubleClickCapture | `MouseEventHandler` | | |
| onMouseDown | `MouseEventHandler` | | |
| onMouseDownCapture | `MouseEventHandler` | | |
| onMouseEnter | `MouseEventHandler` | | |
| onMouseLeave | `MouseEventHandler` | | |
| onMouseMove | `MouseEventHandler` | | |
| onMouseMoveCapture | `MouseEventHandler` | | |
| onMouseOut | `MouseEventHandler` | | |
| onMouseOutCapture | `MouseEventHandler` | | |
| onMouseOver | `MouseEventHandler` | | |
| onMouseOverCapture | `MouseEventHandler` | | |
| onMouseUp | `MouseEventHandler` | | |
| onMouseUpCapture | `MouseEventHandler` | | |
| onTouchCancel | `TouchEventHandler` | | |
| onTouchCancelCapture | `TouchEventHandler` | | |
| onTouchEnd | `TouchEventHandler` | | |
| onTouchEndCapture | `TouchEventHandler` | | |
| onTouchMove | `TouchEventHandler` | | |
| onTouchMoveCapture | `TouchEventHandler` | | |
| onTouchStart | `TouchEventHandler` | | |
| onTouchStartCapture | `TouchEventHandler` | | |
| onPointerDown | `PointerEventHandler` | | |
| onPointerDownCapture | `PointerEventHandler` | | |
| onPointerMove | `PointerEventHandler` | | |
| onPointerMoveCapture | `PointerEventHandler` | | |
| onPointerUp | `PointerEventHandler` | | |
| onPointerUpCapture | `PointerEventHandler` | | |
| onPointerCancel | `PointerEventHandler` | | |
| onPointerCancelCapture | `PointerEventHandler` | | |
| onPointerEnter | `PointerEventHandler` | | |
| onPointerLeave | `PointerEventHandler` | | |
| onPointerOver | `PointerEventHandler` | | |
| onPointerOverCapture | `PointerEventHandler` | | |
| onPointerOut | `PointerEventHandler` | | |
| onPointerOutCapture | `PointerEventHandler` | | |
| onGotPointerCapture | `PointerEventHandler` | | |
| onGotPointerCaptureCapture | `PointerEventHandler` | | |
| onLostPointerCapture | `PointerEventHandler` | | |
| onLostPointerCaptureCapture | `PointerEventHandler` | | |
| onScroll | `UIEventHandler` | | |
| onScrollCapture | `UIEventHandler` | | |
| onWheel | `WheelEventHandler` | | |
| onWheelCapture | `WheelEventHandler` | | |
| onAnimationStart | `AnimationEventHandler` | | |
| onAnimationStartCapture | `AnimationEventHandler` | | |
| onAnimationEnd | `AnimationEventHandler` | | |
| onAnimationEndCapture | `AnimationEventHandler` | | |
| onAnimationIteration | `AnimationEventHandler` | | |
| onAnimationIterationCapture | `AnimationEventHandler` | | |
| onTransitionCancel | `TransitionEventHandler` | | |
| onTransitionCancelCapture | `TransitionEventHandler` | | |
| onTransitionEnd | `TransitionEventHandler` | | |
| onTransitionEndCapture | `TransitionEventHandler` | | |
| onTransitionRun | `TransitionEventHandler` | | |
| onTransitionRunCapture | `TransitionEventHandler` | | |
| onTransitionStart | `TransitionEventHandler` | | |
| onTransitionStartCapture | `TransitionEventHandler` | | |
##### Layout
| Prop | Type | Default | Description |
| ---- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slot | `string \| null` | | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
##### Positioning
| Prop | Type | Default | Description |
| ------ | --------- | ------- | ----------- |
| hidden | `boolean` | | |
##### Accessibility
| Prop | Type | Default | Description |
| ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| id | `string` | | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
### Migration Notes
Coming from Orbiter, you should be aware of the following changes:
* `expansionMode="multiple"` has been replaced with `allowsMultipleExpanded`.
* `borderless` and `bordered` variants are no more. `inline` and `standalone` are the new variants. There is no direct match; the new variants are context-based, depending on whether an accordion is contained or not.
* `autofocus` is removed. It did not make sense to have.
* The `disclosure` component is used instead of `Item`.
* `disabled` is renamed to `isDisabled` on the item/disclosure.
## Address
A specialized component to represent an HTML address element.
```tsx
import { Address, Link } from "@hopper-ui/components";
export default function Example() {
return (
media@spacex.com
(310) 363-6000
);
}
```
### Usage
An address component accepts all the [address HTML element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/address) and [Hopper styled component props](/styled-system/concepts/styling.md).
## Alert
An Alert is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow.
* Source:
Alerts work best when used for short tasks or to warn the user to task relevant information. Alerts are useful in many scenarios; they are less disorientating than navigating a user to a new page for simple tasks or knowledge gathering. However, Alerts are disruptive and can be distracting to the user. Use them sparingly.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
### Anatomy
#### Structure
```tsx
/* (Required) The heading of the Alert */
/* (Required) The content of the Alert */
```
#### Composed Components
A `Alert` uses the following components:
| Component | Description |
| --------- | --------------------------------------------------------------------------- |
| Content | A placeholder for the main content section of a component. |
| Heading | A heading is a primitive component matching Hopper's typography type scale. |
### Usage
#### Default
An alert must have a heading, some content and a primary button label.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Secondary button
An alert can have a secondary button.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Cancel button
An alert can have a cancel button.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Disabled buttons
An alert primary and secondary buttons can be disabled.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Confirmation
Use a confirmation alert when a non-destructive action is required from a user.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Destructive
Use a destructive alert to confirm a permanent change, like deleting data.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Frog-tastrophe!
Something went wrong in the pond. Better leap out before it gets warty!
);
}
```
#### Not Dismissable
An alert can be undismissable.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Controlled
The open state can be handled in controlled mode.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
import { useCallback, useState } from "react";
export default function Example() {
const [isOpen, setIsOpen] = useState(false);
const handleOpenChange = useCallback((open: boolean) => {
setIsOpen(open);
}, [setIsOpen]);
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Pending
An alert can show a pending state. This is useful when you want to show that an action is in progress.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
import { useCallback, useState } from "react";
export default function Example() {
const [isLoading, setIsLoading] = useState(false);
const [isOpen, setIsOpen] = useState(false);
const handleOpenChange = useCallback((open: boolean) => {
if (isLoading && !open) {
return;
}
setIsOpen(open);
}, [setIsOpen, isLoading]);
const handlePrimaryButtonClick = useCallback(async () => {
setIsLoading(true);
await new Promise(resolve => setTimeout(resolve, 3000));
setIsLoading(false);
setIsOpen(false);
}, []);
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
#### Sizes
A Alert can be small or medium. The default size is medium.
```tsx
import { Alert, type AlertProps, AlertTrigger, Button, Content, Heading, Stack } from "@hopper-ui/components";
export default function Example() {
const alert = (size: AlertProps["size"]) => (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
return (
{alert("sm")}
{alert("md")}
);
}
```
#### Responsive sizes
A Alert can have different size in mobile and desktop view.
```tsx
import { Alert, AlertTrigger, Button, Content, Heading } from "@hopper-ui/components";
export default function Example() {
return (
Ribbit Reminder!
Your changes have been saved—no need to leap again. Hop along, hero!
);
}
```
### Best Practices
#### Use alerts sparingly
Don't overuse alerts. They are disruptive and can easily annoy the user if used incorrectly or too frequently. When alerts are used for non-workflow related tasks, it is likely a user will start ignoring or dismissing the alert without fully understanding the content. This can cause users to make hurried or impulsive choices when dealing with more critical alerts.
#### Alerts should be user initiated
A user action, such as clicking a button, should trigger the alert to open. Don't interrupt the user by opening an alert when they aren't expecting it. Avoid system generated pop-ups that distract the user while working. Triggers can either be a direct or indirect consequence of a user's action. An example of an indirect action is a user closing a tab with unsaved content that then causes an alert to ask if they want to save their changes before closing. If the system is autogenerating an alert that is not a consequence of a user's action, but a response to processes happening in the background, then a toast notification should be used instead.
#### Keep alert tasks simple and focused
Alert tasks should be direct and easy to complete. Avoid feature creep in alerts where a once simple alert has become bloated with interactions. When deciding to use an alert consider how the task could expand in the future and if an alert will be able to effectively incorporate additions.
#### Dismissing an alert
* Task completion: clicking the primary action will complete the task and automatically close the alert
* Cancel button: clicking the Cancel button will close the modal and return the user to its previous context. Cancel undoes all applied changes.
* X: Clicking the Dismiss button at the upper right will close the alert without submitting any data and return the user to its previous context.
* Esc: Press ESC on the keyboard.
### Props
#### Alert
| Prop | Type | Default | Description |
| ----------------------- | ------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| autoFocusButton | `"primary" \| "secondary" \| "cancel"` | | The button to focus by default when the alert open. |
| cancelButtonLabel | `string` | | The cancel button label. |
| isDismissable | `boolean` | true | Whether or not the dialog should close on outside interactions. |
| primaryButtonDisabled | `boolean` | | Whether or not the primary button is disabled. |
| primaryButtonLabel | `string` | | The primary button label. |
| secondaryButtonDisabled | `boolean` | | Whether or not the secondary button is disabled. |
| secondaryButtonLabel | `string` | | The secondary button label. |
| variant | `"confirmation" \| "destructive"` | "confirmation" | The visual style of the Alert. |
| size | `ResponsiveProp<"sm" \| "md">` | "md" | The size of the Alert. |
| overlayProps | `Partial` | | Additional props to render on the wrapper element. |
| isLoading | `boolean` | | Whether or not the Alert is loading. |
| style | `CSSProperties` | | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. |
| children | `ReactNode \| ((opts: DialogRenderProps) => ReactNode)` | | Children of the dialog. A function may be provided to access a function to close the dialog. |
| className | `string` | | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| dir | `string` | | |
| lang | `string` | | |
| inert | `boolean` | | |
| translate | `"yes" \| "no"` | | |
| isOpen | `boolean` | | Whether the overlay is open by default (controlled). |
| defaultOpen | `boolean` | | Whether the overlay is open by default (uncontrolled). |
##### Events
| Prop | Type | Default | Description |
| --------------------------- | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onCancelButtonClick | `(() => void)` | | Called when the cancel button is clicked |
| onPrimaryButtonClick | `(() => void)` | | Called when the primary button is clicked. |
| onSecondaryButtonClick | `(() => void)` | | Called when the secondary button is clicked. |
| onOpenChange | `((isOpen: boolean) => void)` | | Handler that is called when the alert's open state changes. This handler is only called when the alert is not used inside a `AlertTrigger`. Use the `onOpenChange` prop of `AlertTrigger` instead if it's part of a trigger |
| onClick | `MouseEventHandler` | | |
| onClickCapture | `MouseEventHandler` | | |
| onAuxClick | `MouseEventHandler` | | |
| onAuxClickCapture | `MouseEventHandler` | | |
| onContextMenu | `MouseEventHandler` | | |
| onContextMenuCapture | `MouseEventHandler` | | |
| onDoubleClick | `MouseEventHandler` | | |
| onDoubleClickCapture | `MouseEventHandler` | | |
| onMouseDown | `MouseEventHandler` | | |
| onMouseDownCapture | `MouseEventHandler` | | |
| onMouseEnter | `MouseEventHandler` | | |
| onMouseLeave | `MouseEventHandler` | | |
| onMouseMove | `MouseEventHandler` | | |
| onMouseMoveCapture | `MouseEventHandler` | | |
| onMouseOut | `MouseEventHandler` | | |
| onMouseOutCapture | `MouseEventHandler` | | |
| onMouseOver | `MouseEventHandler` | | |
| onMouseOverCapture | `MouseEventHandler` | | |
| onMouseUp | `MouseEventHandler` | | |
| onMouseUpCapture | `MouseEventHandler` | | |
| onTouchCancel | `TouchEventHandler` | | |
| onTouchCancelCapture | `TouchEventHandler` | | |
| onTouchEnd | `TouchEventHandler` | | |
| onTouchEndCapture | `TouchEventHandler` | | |
| onTouchMove | `TouchEventHandler` | | |
| onTouchMoveCapture | `TouchEventHandler` | | |
| onTouchStart | `TouchEventHandler` | | |
| onTouchStartCapture | `TouchEventHandler` | | |
| onPointerDown | `PointerEventHandler` | | |
| onPointerDownCapture | `PointerEventHandler` | | |
| onPointerMove | `PointerEventHandler` | | |
| onPointerMoveCapture | `PointerEventHandler` | | |
| onPointerUp | `PointerEventHandler` | | |
| onPointerUpCapture | `PointerEventHandler` | | |
| onPointerCancel | `PointerEventHandler` | | |
| onPointerCancelCapture | `PointerEventHandler` | | |
| onPointerEnter | `PointerEventHandler` | | |
| onPointerLeave | `PointerEventHandler` | | |
| onPointerOver | `PointerEventHandler` | | |
| onPointerOverCapture | `PointerEventHandler` | | |
| onPointerOut | `PointerEventHandler` | | |
| onPointerOutCapture | `PointerEventHandler` | | |
| onGotPointerCapture | `PointerEventHandler` | | |
| onGotPointerCaptureCapture | `PointerEventHandler` | | |
| onLostPointerCapture | `PointerEventHandler` | | |
| onLostPointerCaptureCapture | `PointerEventHandler` | | |
| onScroll | `UIEventHandler` | | |
| onScrollCapture | `UIEventHandler` | | |
| onWheel | `WheelEventHandler` | | |
| onWheelCapture | `WheelEventHandler` | | |
| onAnimationStart | `AnimationEventHandler` | | |
| onAnimationStartCapture | `AnimationEventHandler` | | |
| onAnimationEnd | `AnimationEventHandler` | | |
| onAnimationEndCapture | `AnimationEventHandler` | | |
| onAnimationIteration | `AnimationEventHandler` | | |
| onAnimationIterationCapture | `AnimationEventHandler` | | |
| onTransitionCancel | `TransitionEventHandler` | | |
| onTransitionCancelCapture | `TransitionEventHandler` | | |
| onTransitionEnd | `TransitionEventHandler` | | |
| onTransitionEndCapture | `TransitionEventHandler` | | |
| onTransitionRun | `TransitionEventHandler` | | |
| onTransitionRunCapture | `TransitionEventHandler` | | |
| onTransitionStart | `TransitionEventHandler` | | |
| onTransitionStartCapture | `TransitionEventHandler` | | |
##### Layout
| Prop | Type | Default | Description |
| ---- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slot | `string \| null` | | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
##### Positioning
| Prop | Type | Default | Description |
| ------ | --------- | ------- | ----------- |
| hidden | `boolean` | | |
##### Accessibility
| Prop | Type | Default | Description |
| ---------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| role | `"dialog" \| "alertdialog"` | 'dialog' | The accessibility role for the dialog. |
| id | `string` | | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| aria-label | `string` | | Defines a string value that labels the current element. |
| aria-labelledby | `string` | | Identifies the element (or elements) that labels the current element. |
| aria-describedby | `string` | | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | | Identifies the element (or elements) that provide a detailed, extended description for the object. |
#### AlertTrigger
| Prop | Type | Default | Description |
| ----------- | --------- | ------- | ------------------------------------------------------ |
| isOpen | `boolean` | | Whether the overlay is open by default (controlled). |
| defaultOpen | `boolean` | | Whether the overlay is open by default (uncontrolled). |
##### Events
| Prop | Type | Default | Description |
| ------------ | ----------------------------- | ------- | ------------------------------------------------------------- |
| onOpenChange | `((isOpen: boolean) => void)` | | Handler that is called when the overlay's open state changes. |
### Migration Notes
Coming from Orbiter, you should be aware of the following changes:
* `dismissable` has been renamed `isDismissable`.
* `wrapperProps` has been renamed `overlayProps`.
* `onClose` has been removed.
## Article
A specialized component to represent an HTML article element.
```tsx
import { Aside, Paragraph } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
### Usage
An article component accepts all the [article HTML element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/article) and [Hopper styled component props](/styled-system/concepts/styling.md).
## Aside
A specialized component to represent an HTML aside element.
```tsx
import { Aside, Paragraph } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
### Usage
An aside component accepts all the [aside HTML element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/aside) and [Hopper styled component props](/styled-system/concepts/styling.md).
## Avatar
Avatars are used to represent a user, a team or another entity in the Workleap ecosystem. They are often paired with text where room is available.
* Source:
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
### Usage
#### Local Image
An avatar can display a local image.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Remote image
An avatar can fetch a remote image.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Fallback image
A fallback image can be set in case the `src` fails to load.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Loading Failure
When an image fails to load, a default image will be displayed.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Double Failure
When the fallback image fails to load, a default image will be displayed.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Src and Fallback Bypass
If no fallback image is provided and the image fails to load, the initials will be displayed instead.
```tsx
import { Avatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Anonymous
An anonymous avatar can be displayed.
```tsx
import { AnonymousAvatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Deleted
A deleted avatar can be displayed.
```tsx
import { DeletedAvatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Broken
A broken avatar can be displayed.
```tsx
import { BrokenAvatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Sizes
An avatar can be displayed in different sizes.
* Extra small (16px): use in tightly condensed layouts. This size can only accommodate one letter when using the Initials variant.
* Small (24px): use when the medium size is too big for the layout, or when the avatar has less importance in the context.
* Medium (32px): use as the default size
* Large (48px): use when an avatar is a focal point, such on a member page header
* Extra large (64px): use when an avatar is a focal point, such on a member page header
```tsx
import { Avatar, Stack, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Disabled
An avatar can be disabled.
```tsx
import { AnonymousAvatar, Avatar, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Pressable
An avatar can be pressed, which will trigger an action when pressed.
```tsx
import { AnonymousAvatar, Avatar, BrokenAvatar, DeletedAvatar, Inline } from "@hopper-ui/components";
import { useCallback } from "react";
export default function Example() {
const handlePress = useCallback(() => {
alert("Avatar pressed!");
}, []);
return (
);
}
```
#### Customize the image props
Using a custom hook to retry loading the image up to 5 times with a 250ms delay.
```tsx
import { Avatar, Paragraph, Stack } from "@hopper-ui/components";
import { type ReactEventHandler, useEffect, useState } from "react";
function useAsyncImage(src: string, retryCount = 5, delay = 250) {
const [currentSrc, setCurrentSrc] = useState(src);
const [isLoaded, setIsLoaded] = useState(false);
const [failureCount, setFailureCount] = useState(0);
useEffect(() => {
if (isLoaded || failureCount >= retryCount) {
return;
}
const loadImage = () => {
const image: HTMLImageElement = new Image();
image.src = currentSrc;
image.onload = () => {
setIsLoaded(true);
};
image.onerror = () => {
if (failureCount < retryCount) {
setFailureCount(prevCount => prevCount + 1);
setCurrentSrc(src); // Trigger retry by resetting src
}
};
};
const timeoutId = setTimeout(loadImage, delay);
return () => {
clearTimeout(timeoutId);
};
}, [currentSrc, isLoaded, failureCount, retryCount, delay, src]);
const onError: ReactEventHandler | undefined = () => {
if (failureCount < retryCount) {
setFailureCount(prevCount => prevCount + 1);
setCurrentSrc(src); // Manually trigger retry
}
};
return [isLoaded ? currentSrc : undefined, onError, failureCount] as const;
}
export default function Example() {
const [src, handleError, failureCount] = useAsyncImage("https://example.com/image.jpg");
const [src2, handleError2, failureCount2] = useAsyncImage("https://i.pravatar.cc/96?img=1");
return (
The avatar failed to load {failureCount} times.The avatar failed to load {failureCount2} times.
);
}
```
#### AvatarGroup
An avatar group can be used to display multiple avatars.
```tsx
import { Avatar, AvatarGroup } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
##### Too many avatars
When there are too many avatars, a counter will be displayed.
```tsx
import { AnonymousAvatar, Avatar, AvatarGroup, DeletedAvatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
##### Sizes
An avatar group can be displayed in different sizes.
```tsx
import { Avatar, AvatarGroup, Stack } from "@hopper-ui/components";
export default function Example() {
const avatars = [
,
,
];
return (
{avatars}
{avatars}
{avatars}
{avatars}
{avatars}
{avatars}
);
}
```
##### Pressable avatars
An avatar group can have pressable avatars, which will trigger an action when pressed.
```tsx
import { Avatar, AvatarGroup } from "@hopper-ui/components";
export default function Example() {
return (
alert("John Doe")} />
alert("Chris Dalton")} />
);
}
```
##### Max number of avatars
An avatar group can be limited to a maximum number of avatars.
```tsx
import { AnonymousAvatar, Avatar, AvatarGroup, DeletedAvatar } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
### Best Practices
Any time you use an image to communicate a concept in Workleap, it's important to use descriptive alt text. Doing this is important for accessibility because it allows screen readers to describe what's in the image to people who may not be able to see it.
### Props
#### Avatar
| Prop | Type | Default | Description |
| ----------- | ---------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fallbackSrc | `string \| null` | "BrokenImageRichIcon" | The src of the image to display if the image fails to load. If set to null, the initials will be displayed instead. |
| imageProps | `AvatarImageBaseProps` | | Props to add to the img element when src is provided. |
| isDisabled | `boolean` | | Whether or not the avatar is disabled. |
| name | `string` | | The name of the Avatar. This will be used for the alt text of the image or the initials if no image is provided. |
| size | `ResponsiveProp` | "md" | The size of the avatar. |
| src | `string` | | The src of the image to display. If not provided, the initials will be displayed instead. |
| className | `string \| ((values: AvatarRenderProps & { defaultClassName: string; }) => string)` | | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| style | `CSSProperties \| ((values: AvatarRenderProps & { defaultStyle: CSSProperties; }) => CSSProperties)` | | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
##### Events
| Prop | Type | Default | Description |
| ------- | ------------------------------- | ------- | --------------------------------- |
| onPress | `((event: PressEvent) => void)` | | Called when the avatar is pressed |
##### Layout
| Prop | Type | Default | Description |
| ---- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slot | `string \| null` | | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
##### Accessibility
| Prop | Type | Default | Description |
| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| aria-label | `string` | | Defines a string value that labels the current element. |
| aria-labelledby | `string` | | Identifies the element (or elements) that labels the current element. |
| aria-describedby | `string` | | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | | Identifies the element (or elements) that provide a detailed, extended description for the object. |
#### AvatarGroup
| Prop | Type | Default | Description |
| ----------------- | -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| size | `ResponsiveProp` | "md" | The size of the avatar. |
| maxNumberOfAvatar | `ResponsiveProp` | 3 | The maximum number of avatars to show before showing the overflow indicator. |
| wrap | `ResponsiveProp` | true | Whether or not to wrap the avatars. |
| reverse | `boolean` | | Whether or not to reverse the order of the avatars. |
| align | `ResponsiveProp` | 'start' | The alignment of the avatars within the AvatarGroup. |
| children | `AvatarGroupElement \| AvatarGroupElement[]` | | The content of the AvatarGroup. |
| style | `CSSProperties` | | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. |
| className | `string` | | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
##### Layout
| Prop | Type | Default | Description |
| ---- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slot | `string \| null` | | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
##### Accessibility
| Prop | Type | Default | Description |
| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| id | `string` | | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| aria-label | `string` | | Defines a string value that labels the current element. |
| aria-labelledby | `string` | | Identifies the element (or elements) that labels the current element. |
| aria-describedby | `string` | | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | | Identifies the element (or elements) that provide a detailed, extended description for the object. |
### Migration Notes
Coming from Orbiter, you should be aware of the following changes:
* `retryCount` has been removed.
* `onClick` has been renamed to `onPress` to be closer to the [React Aria API](https://react-spectrum.adobe.com/react-aria/Button.html#events).
## Badge
A badge is used to bring attention to an element.
* Source:
A badge will communicate a small piece of information that users may be interested in, but would not impede them from achieving their task. They can also display the amount of item for an object.
```tsx
import { Badge } from "@hopper-ui/components";
export default function Example() {
return (
12
);
}
```
### Usage
#### Disabled
A disabled badge is usually used inside other components that may be disabled, like a tag or a list box.
```tsx
import { Badge } from "@hopper-ui/components";
export default function Example() {
return (
12
);
}
```
#### Indeterminate
An indeterminate badge is used when the value is unknown or not applicable.
```tsx
import { Badge } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Variants
The different variants of a badge.
```tsx
import { Badge, Inline } from "@hopper-ui/components";
export default function Example() {
return (
BETANEW50
);
}
```
#### High Count
If a value above 99 is needed, use `99+` instead of the number.
```tsx
import { Badge } from "@hopper-ui/components";
export default function Example() {
return (
99+
);
}
```
#### Text
A badge can have any text content.
```tsx
import { Badge } from "@hopper-ui/components";
export default function Example() {
return (
New
);
}
```
### Best Practices
Badges benefit users by:
* Being clearly labeled with short, scannable text
* Being positioned to clearly identify the object they're informing or labelling.
#### Qualificative Badges
Badges can be used to qualify an object with a word or two. Most likely, badges will be used in specific situations, but are not limited to:
* New: to announce a new functionality or feature in Workleap. This badge should have a defined lifespan where at the end it is removed.
* Beta: to highlight that a functionality or feature is being released early to test and gather feedback. This badge should be accompanied by a Popover to provide more information to the user. This badge should have a defined lifespan where at the end it is removed.
#### Quantitative Badges
Badges can also be used to count the number of item for an object. To ensure the best scannability quantitative badges should:
* Not be displayed if the count is at zero.
* Display “+99” if the count goes beyond 99 items.
* Use the same interaction state of the related object.
### Props
| Prop | Type | Default | Description |
| --------------- | --------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| variant | `BadgeVariant` | "primary" | The visual style of the badge. |
| isDisabled | `boolean` | | Whether or not the badge is disabled. |
| isIndeterminate | `boolean` | | Whether or not the badge is indeterminate and should just be a dot. This will ignore any children. |
| children | `ReactNode \| ((values: BadgeRenderProps & { defaultChildren: ReactNode; }) => ReactNode)` | | The children of the component. A function may be provided to alter the children based on component state. |
| className | `string \| ((values: BadgeRenderProps & { defaultClassName: string; }) => string)` | | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| style | `CSSProperties \| ((values: BadgeRenderProps & { defaultStyle: CSSProperties; }) => CSSProperties)` | | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
##### Layout
| Prop | Type | Default | Description |
| ---- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slot | `string \| null` | | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
##### Accessibility
| Prop | Type | Default | Description |
| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| aria-label | `string` | | Defines a string value that labels the current element. |
| aria-labelledby | `string` | | Identifies the element (or elements) that labels the current element. |
| aria-describedby | `string` | | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | | Identifies the element (or elements) that provide a detailed, extended description for the object. |
### Migration Notes
Coming from Orbiter, you should be aware of the following changes:
* `highlight` is not supported.
* `pushed` is not supported.
* `reverse` is not supported, use `flex-direction` or `row-reverse` instead.
* `size` is not supported.
* `variant` has different values.
* `icon` variant it not supported.
* `wrapperProps` has been removed.
* Badge is no longer floating. Use the `FloatingBadge` component to add this feature.
* `FloatingBadge` has new props such as `placement` and `offset`.
* `overlap` is used inside `FloatingBadge` and the new values are `circular` and `rectangular`.
## Box
A flexible container component that can render as any HTML element or React component. Supports all styled system props for consistent spacing, layout, and styling.
* Source:
```tsx
import { Box } from "@hopper-ui/components";
export default function Example() {
return (
Software built for everyone to do their best work.
);
}
```
### Best Practices
The `Box` component should not be used in place of standard HTML elements. Use `Div` or `Span` directly for that purpose. `Box` is meant to provide styled system properties to components that already accept `style` and `className`, such as third-party components.
`Box` should:
* Be used to **augment** components (often third-party) with layout/spacing/visual props when those components accept `className`/`style`.
* Keep the DOM **semantic**: always prefer the correct native element, or [use `htmlElement()` function](/styled-system/concepts/html-elements.md) for missing tags, instead of forcing `Box`.
* Use the `as` prop **sparingly**, and typically only to target non-native components (e.g., `as={RACButton}`) or in rare conditional cases where semantics truly change.
* Avoid introducing conflicting layout: prefer composing spacing on the **outermost** appropriate element.
#### Do's and Don'ts
**Rule 1**
* ✅ Do:
```tsx
import { Box } from "@hopper-ui/components";
import { Button as RACButton } from "react-aria-components";
export function Example() {
return (
Click me
);
}
```
Use Box to add spacing/layout to a third-party component that accepts className/style
* 🚫 Don't:
```tsx
import { Box } from "@hopper-ui/components";
export function Example() {
return (
<>
This should just be a <Inline>
This should just be a <Stack>
);
}
```
Use Box as a generic \ or \ substitute
**Rule 2**
* ✅ Do:
```tsx
import { htmlElement } from "@hopper-ui/styled-system";
const IFrame = htmlElement("iframe");
export function Example() {
return (
);
}
```
Create missing HTML elements with htmlElement() (e.g., IFrame) and use them directly
* 🚫 Don't:
```tsx
import { Box } from "@hopper-ui/components";
export function Example() {
return (
);
}
```
Render missing HTML tags via Box (e.g., \)
**Rule 3**
* ✅ Do:
```tsx
import { Box } from "@hopper-ui/components";
export function Example({ isClickable }: { isClickable: boolean }) {
return (
It is acceptable but not recommended
);
}
```
Use the 'as' prop to flip between components
**Rule 4**
* 🚫 Don't:
```tsx
import { Box, Card } from "@hopper-ui/components";
export function Example() {
return (
Too many Boxes…
);
}
```
Wrap everything in Box or use it to override intrinsic spacing/styles of the child component
### Props
| Prop | Type | Default | Description |
| ---- | ------------- | ------- | ------------------------------ |
| as | `ElementType` | "div" | The element type to render as. |
## Button
A button allows a user to initiate an action.
* Source:
* Aria:
```tsx
import { Button, Text } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
export default function Example() {
return (
);
}
```
### Anatomy
#### Structure
```tsx
```
#### Composed Components
A `Button` uses the following components:
| Component | Description |
| --------- | ---------------------------------------------------------------------------------- |
| Icon | An icon component is used to render a custom icon. |
| IconList | An IconList encapsulates a collection of icons. |
| Text | A text component is a primitive component matching Hopper's typography type scale. |
### Usage
#### Variants
Each button variant has a particular function and its design signals that function to the user. It is therefore very important that the different variants are implemented consistently across products so that they message the correct actions.
```tsx
import { Button, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
| Variant | Purpose |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Primary | For the principal call to action on the page. Primary buttons should only appear once per screen (not including the application header, modal or side panel). |
| Secondary | For secondary actions on each page. Secondary buttons can be used in conjunction with a primary button or on its own. Paired with a Primary button, the secondary button usually performs the negative action of the set, such as “Cancel.” |
| Ghost | For less prominent, and sometimes independent, actions. Ghost buttons can be used in isolation or paired with a primary button when there are multiple calls to action. Ghost buttons can also be used for sub-tasks on a page where a primary button for the main and final action is present. |
| Upsell | For upsell actions that relates to upgrading an account or a plan. Use the upsell button to distinguish from an existing primary button. In some case a primary button can be used in its place when the general context of the page is about upselling. |
| Danger | For actions that could have destructive effects on the user's data. |
#### Sizes
A button can vary in size.
```tsx
import { Button, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Disabled
A button can be disabled.
```tsx
import { Button, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Loading
A button can show a loading indicator. The button text is hidden but the button maintains the width that it would have if the text were visible.
```tsx
import { Button, Inline } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
#### Pending
Buttons can indicate that a quick progress task is taking place (e.g., saving settings on a server). After a 1 second delay, an indeterminate spinner will be displayed in place of the button label and icon.
```tsx
import { Button } from "@hopper-ui/components";
import { useCallback, useState } from "react";
export default function Example() {
const [isLoading, setIsLoading] = useState(false);
const handlePress = useCallback(() => {
setIsLoading(true);
setTimeout(() => {
setIsLoading(false);
}, 3000);
}, [setIsLoading]);
return (
);
}
```
#### Fluid
A button can be expanded to full width to fill its parent container.
```tsx
import { Button, Inline, Text } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
export default function Example() {
return (
);
}
```
#### Icon Only
A button can contain only an icon. An accessible name must be provided through [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) prop. See also [WCAG practices](https://www.w3.org/TR/WCAG20-TECHS/ARIA6.html).
```tsx
import { Button, Inline } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
export default function Example() {
return (
);
}
```
#### Icon
A button can contain icons.
```tsx
import { Button, Inline, Text } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
export default function Example() {
return (
);
}
```
#### End Icon
Nonstandard end icons can be provided to handle special cases. However, think twice before adding end icons, start icons should be your go-to.
```tsx
import { Button, Inline, Text } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
export default function Example() {
return (
);
}
```
### Best Practices
Buttons are clickable elements that are used to trigger actions. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. Button labels express what action will occur when the user interacts with it. Use buttons to communicate actions users can take and to allow users to interact with the page. Each page should have only one primary button, and any remaining calls to action should be represented as lower emphasis buttons.
#### Emphasis
You don't necessarily need to use the buttons in the order that their labels imply. For example, you don't always need to use the secondary button as the second button in your layout. The most important thing is to establish a visual hierarchy between the buttons in your interface. Keep these best practices in mind.
##### A single, high-emphasis button
As a general rule, a layout should contain a single high-emphasis button that makes it clear that other buttons have less importance in the hierarchy. This high-emphasis button commands the most attention.
##### Multiple button emphasis
A high-emphasis button can be accompanied by medium- and low-emphasis buttons that perform less important actions. Keep in mind that you should only groups together calls to action that have a relationship to one another.
#### Alignment
Alignment refers to whether the buttons are aligned to the right or the left of a container or layout. Buttons are unique, more so than any other component, in that their alignment depends on where they appear and whether or not they're contained within another component.
As a general rule, on full-page designs, the primary button is on the right side of the page. When the browser window is large and the user is scrolling to read, it's best to have the primary button where the users's attention has been focused all along. Whereas in wizards, where a user is progressing through a series of steps or modal, the primary action traditionally sits at the bottom right. Buttons within components are also right-aligned.
#### Do's and Don'ts
**Rule 1**
* ✅ Do:
```tsx
import { Button, Text } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
;
```
When a Button contains anything other than a single text node, the accompanying text must be wrapped in a \ component.
* 🚫 Don't:
```tsx
import { Button } from "@hopper-ui/components";
import { SparklesIcon } from "@hopper-ui/icons";
;
```
Use text without \ if you have anything other than a single text node inside the Button.
**Rule 2**
* ✅ Do:
```tsx
import { Button } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
Use 1 or 2 words, no longer than 4 words, with fewer than 20 characters including spaces.
* 🚫 Don't:
```tsx
import { Button } from "@hopper-ui/components";
export default function Example() {
return (
);
}
```
Use punctuation marks such as periods or exclamation points.
**Rule 3**
* ✅ Do:
Use links when the desired action is to take the user to a new page.
* 🚫 Don't:
Use buttons as navigational elements.
### Props
| Prop | Type | Default | Description |
| -------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| variant | `ButtonVariant` | "primary" | The visual style of the button. |
| size | `ResponsiveProp` | "md" | A button can vary in size. |
| isFluid | `ResponsiveProp` | | Whether or not the button takes up the width of its container. |
| isLoading | `boolean` | | A button can show a loading indicator. |
| spinnerProps | `SpinnerProps` | | The props for the Spinner. |
| form | `string` | | The `