RSUITE

https://rsuitejs.com/components/
Admin
RSUITE is a comprehensive React UI component library providing a rich set of modular, customizable...
Tokens:5,836
Snippets:64
Trust Score:9.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Nice Modal Dependency

Source: https://rsuitejs.com/components/modal-integrations

Install the `@ebay/nice-modal-react` dependency using npm.

```bash
npm install @ebay/nice-modal-react
```

--------------------------------

### Installation and Basic Usage

Source: https://rsuitejs.com/components/use-toaster

Instructions on how to install the CustomProvider and use the useToaster hook to display messages and notifications.

```APIDOC
## Installation and Basic Usage

### Install CustomProvider
First, install `CustomProvider` at the root of your application to manage the toast rendering container.

```javascript
import { CustomProvider } from 'rsuite';

function App({ children }) {
  return <CustomProvider>{children}</CustomProvider>;
}
```

### Using useToaster
Use the `useToaster` hook to access methods for displaying toasts.

```javascript
import { useToaster, Message, Notification } from 'rsuite';

function MyApp() {
  const toaster = useToaster();

  // Display a message
  toaster.push(<Message>message</Message>);

  // Display a notification
  toaster.push(<Notification>notification</Notification>);
}
```
```

--------------------------------

### Installation and Basic Usage

Source: https://rsuitejs.com/components/use-dialog

Before using the `useDialog` hook, you must install `CustomProvider` at the root of your application to manage the dialog rendering container. Then, you can import and use `useDialog` to trigger various dialog types.

```APIDOC
### Install CustomProvider

```javascript
import { CustomProvider } from 'rsuite';

function App({ children }) {
  return <CustomProvider>{children}</CustomProvider>;
}
```

### Using useDialog

```javascript
import { useDialog } from 'rsuite';

function MyApp() {
  const dialog = useDialog();

  // Alert dialog
  dialog.alert('Hello, world!');

  // Confirm dialog
  dialog.confirm('Are you sure?');

  // Prompt dialog
  dialog.prompt('What is your name?');

  // Custom dialog
  dialog.open(CustomDialog);
}
```
```

--------------------------------

### Install CustomProvider

Source: https://rsuitejs.com/components/use-dialog

Install CustomProvider at the root of your application to manage the dialog rendering container. This is a prerequisite for using the useDialog hook.

```jsx
import { CustomProvider } from 'rsuite';

function App({ children }) {
  return <CustomProvider>{children}</CustomProvider>;
}
```

--------------------------------

### Use with Modal

Source: https://rsuitejs.com/components/use-media-query

Example of using useMediaQuery to make the Modal component responsive. On large screens, the Modal has a fixed size; on small screens, it becomes full-screen.

```javascript
// PreviewCode for Modal responsiveness would go here if available
```

--------------------------------

### Use with RadioTile

Source: https://rsuitejs.com/components/use-media-query

Example of using useMediaQuery to create a responsive RadioTile component. On large screens, RadioTiles display on the same line; on small screens, they display on different lines.

```javascript
// PreviewCode for RadioTile responsiveness would go here if available
```

--------------------------------

### Programmatic Whisper Control

Source: https://rsuitejs.com/components/whisper

Examples of using the ref to manually open, close, or update the position of the overlay.

```javascript
// Open overlay on button click
<Button onClick={() => whisperRef.current?.open()}>Show Tooltip</Button>;

// Show overlay after data is loaded
useEffect(() => {
  if (dataLoaded) {
    whisperRef.current?.open(300); // Show after 300ms
  }
}, [dataLoaded]);

// Update overlay position when content changes
const handleResize = useCallback(() => {
  whisperRef.current?.updatePosition();
}, []);
```

--------------------------------

### useDialog Hook

Source: https://rsuitejs.com/components/use-dialog

The `useDialog` hook provides imperative methods to open different types of dialogs. Ensure `CustomProvider` is installed at the root of your application.

```APIDOC
## `useDialog()`

Returns an object containing the following methods:

### Methods

- **alert** `(message: ReactNode, options?: AlertOptions) => Promise<void>`: Shows an alert dialog.
- **confirm** `(message: ReactNode, options?: ConfirmOptions) => Promise<boolean>`: Shows a confirmation dialog.
- **prompt** `(message: ReactNode, options?: PromptOptions) => Promise<string>`: Shows a prompt dialog.
- **open** `(component: ComponentType, payload?: P, options?: OpenOptions) => Promise<T>`: Shows a custom dialog.

### Type Definitions

#### `AlertOptions`
```typescript
interface AlertOptions {
  title?: string; // Dialog title, defaults to 'Alert'
  okText?: string; // Text for the OK button, defaults to 'OK'
  onClose?: () => void; // Callback when dialog is closed
}
```

#### `ConfirmOptions`
```typescript
interface ConfirmOptions {
  title?: string; // Dialog title, defaults to 'Confirm'
  okText?: string; // Text for the OK button, defaults to 'OK'
  cancelText?: string; // Text for the Cancel button
  severity?: 'info' | 'success' | 'warning' | 'error'; // Visual style of the dialog
  onClose?: (result: boolean) => void; // Callback when dialog is closed
}
```

#### `PromptOptions`
```typescript
interface PromptOptions {
  title?: string; // Dialog title, defaults to 'Confirm'
  okText?: string; // Text for the OK button, defaults to 'OK'
  cancelText?: string; // Text for the Cancel button
  defaultValue?: string; // Default value for the input field
  validate?: (value: string) => [isValid: boolean, errorMessage?: string]; // Validation function
  onClose?: (result: string) => void; // Callback when dialog is closed
}
```

#### `OpenOptions<T>`
```typescript
interface OpenOptions<T> {
  onClose?: (result?: T) => void; // Callback when dialog is closed
}
```
```

--------------------------------

### Responsive RadioTile with useMediaQuery

Source: https://rsuitejs.com/components/use-media-query

Combine useMediaQuery with RadioTile's inline prop to create responsive RadioTile components. On large screens, RadioTiles display inline; on small screens, they stack vertically.

```javascript
const ResponsiveRadioTile = () => {
  const inLg = useMediaQuery('(min-width: 1200px)');

  return (
    <RadioTileGroup inline={inLg} defaultValue="1">
      <RadioTile label="1" value="1">Option 1</RadioTile>
      <RadioTile label="2" value="2">Option 2</RadioTile>
      <RadioTile label="3" value="3">Option 3</RadioTile>
    </RadioTileGroup>
  );
};
```

--------------------------------

### Import useMediaQuery Hook

Source: https://rsuitejs.com/components/use-media-query

Import the useMediaQuery hook from the rsuite library to enable responsive design capabilities.

```javascript
import { useMediaQuery } from 'rsuite';
```

--------------------------------

### Using useDialog Hook

Source: https://rsuitejs.com/components/use-dialog

Demonstrates how to use the useDialog hook to open alert, confirm, and prompt dialogs. The hook returns an object with methods for each dialog type.

```jsx
import { useDialog } from 'rsuite';

function MyApp() {
  const dialog = useDialog();

  // Alert dialog
  dialog.alert('Hello, world!');

  // Confirm dialog
  dialog.confirm('Are you sure?');

  // Prompt dialog
  dialog.prompt('What is your name?');

  // Custom dialog
  dialog.open(CustomDialog);
}
```

--------------------------------

### Using Nice Modal in an Application

Source: https://rsuitejs.com/components/modal-integrations

Wrap your application with `NiceModal.Provider` to enable modal functionality. Show modals using `NiceModal.show` with your custom modal component and its props.

```javascript
import NiceModal from '@ebay/nice-modal-react';
import { MyModal } from './MyModal';

const App = () => {
  return (
    <NiceModal.Provider>
      <Button
        appearance="primary"
        onClick={() => {
          NiceModal.show(MyModal, { id: 'test', name: 'Nate' });
        }}>
        Show Modal
      </Button>
    </NiceModal.Provider>
  );
};

```

--------------------------------

### Responsive Modal with useMediaQuery

Source: https://rsuitejs.com/components/use-media-query

Utilize useMediaQuery to make the Modal component responsive. On large screens, the modal has a fixed size; on small screens, it becomes full-screen.

```javascript
const ResponsiveModal = () => {
  const inLg = useMediaQuery('(min-width: 1200px)');
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open</Button>
      <Modal size={inLg ? 'md' : 'full'} open={open} onClose={() => setOpen(false)}>
        <Modal.Header />
        <Modal.Body />
        <Modal.Footer />
      </Modal>
    </>
  );
};
```

--------------------------------

### Whisper Component - Import

Source: https://rsuitejs.com/components/whisper

How to import the Whisper component into your project.

```APIDOC
## Import

```javascript
import { Whisper } from 'rsuite';
```
```

--------------------------------

### Whisper Component - Basic Usage

Source: https://rsuitejs.com/components/whisper

Demonstrates the basic usage of the Whisper component with default supported overlay elements like Tooltip and Popover.

```APIDOC
## Examples

### Basic Usage

The default supported speaker components are `Tooltip` and `Popover`.

```javascript
// Example usage with Tooltip
<Whisper trigger="hover" speaker={<Tooltip>Hello world!</Tooltip>}>
  <Button>Hover me</Button>
</Whisper>

// Example usage with Popover
<Whisper trigger="click" speaker={<Popover title="Title">Hello world!</Popover>}>
  <Button>Click me</Button>
</Whisper>
```
```

--------------------------------

### Whisper Component - Methods

Source: https://rsuitejs.com/components/whisper

Information on how to use the Whisper component's methods via `ref` to programmatically control the overlay.

```APIDOC
### Whisper Methods

Whisper provides several methods available via `ref` to programmatically control the overlay display and positioning. These methods are useful when you need to manually trigger overlay actions, such as:
  * Showing/hiding tooltips based on business logic
  * Updating overlay position after content changes
  * Creating custom interaction logic

Get the component instance using `ref`:

```javascript
import React, { useRef } from 'react';
import { Whisper, Button, Tooltip } from 'rsuite';

function MyComponent() {
  const whisperRef = useRef();

  return (
    <Whisper ref={whisperRef} speaker={<Tooltip>This is a tooltip</Tooltip>}>
      <Button>Hover me</Button>
    </Whisper>
  );
}
```

Method | Type Definition | Description
---|---|---
open | `(delay?: number) => void` | Manually open the overlay with an optional `delay` in milliseconds
close | `(delay?: number) => void` | Manually close the overlay with an optional `delay` in milliseconds
updatePosition | `() => void` | Manually update the overlay position when content changes

```javascript
// Example of using methods:

// Open overlay on button click
<Button onClick={() => whisperRef.current?.open()}>Show Tooltip</Button>;

// Show overlay after data is loaded
useEffect(() => {
  if (dataLoaded) {
    whisperRef.current?.open(300); // Show after 300ms
  }
}, [dataLoaded]);

// Update overlay position when content changes
const handleResize = useCallback(() => {
  whisperRef.current?.updatePosition();
}, []);
```
```

--------------------------------

### Access Whisper via Ref

Source: https://rsuitejs.com/components/whisper

Demonstrates how to obtain a reference to the Whisper component instance to access its methods.

```javascript
const whisperRef = useRef();

<Whisper ref={whisperRef} {...}>
  <Button>Hover me</Button>
</Whisper>
```

--------------------------------

### Create a Reusable Modal Component

Source: https://rsuitejs.com/components/modal-integrations

Use `NiceModal.create` to define a modal component that can be reused throughout your application. Ensure `useModal` hook is imported.

```javascript
import { Modal, Button } from 'rsuite';
import NiceModal, { useModal } from '@ebay/nice-modal-react';

export const MyModal = NiceModal.create(({ id, name }) => {
  const modal = useModal();
  return (
    <Modal open={modal.visible} onClose={modal.hide} onExited={modal.remove} backdrop="static">
      <Modal.Header>
        <Modal.Title>Hello React Suite</Modal.Title>
      </Modal.Header>
      <Modal.Body>
        Greetings: {id}, {name}!
      </Modal.Body>
    </Modal>
  );
});
```

--------------------------------

### Whisper Component - Custom Overlay

Source: https://rsuitejs.com/components/whisper

Shows how to customize the overlay content using the `speaker` prop and supports delay for opening.

```APIDOC
### Custom Overlay

You can customize the overlay content using the `speaker` prop. The following example demonstrates how to create a custom overlay component with delay support.

```javascript
<Whisper trigger="hover" delay={1000} speaker={<Tooltip>Open after 1000ms</Tooltip>}>
  <Button>Hover me</Button>
</Whisper>
```
```

--------------------------------

### Placement Type Definition

Source: https://rsuitejs.com/components/whisper

TypeScript definition for the available overlay placement options.

```typescript
type Placement =
  | 'top'
  | 'bottom'
  | 'right'
  | 'left'
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd'
  | 'auto'
  | 'autoVerticalStart'
  | 'autoVerticalEnd'
  | 'autoHorizontalStart'
  | 'autoHorizontalEnd';
```

--------------------------------

### Using useToaster Hook

Source: https://rsuitejs.com/components/use-toaster

Use the useToaster hook to access methods for displaying toast messages and notifications. Import Message and Notification components for different toast types.

```jsx
import { useToaster, Message, Notification } from 'rsuite';

function MyApp() {
  const toaster = useToaster();

  // Display a message
  toaster.push(<Message>message</Message>);


  // Display a notification
  toaster.push(<Notification>notification</Notification>);
}
```

--------------------------------

### Import Whisper Component

Source: https://rsuitejs.com/components/whisper

Standard import statement for the Whisper component from the rsuite library.

```javascript
import { Whisper } from 'rsuite';
```

--------------------------------

### Whisper Component - Props

Source: https://rsuitejs.com/components/whisper

Detailed list of all available props for the Whisper component, their types, default values, and descriptions.

```APIDOC
## Props

### `<Whisper>`

Property | Type `(Default)` | Description
---|---|---
container | HTMLElement | (() => HTMLElement) | Sets the rendering container
controlId | string | Set the `id` on `<Overlay>` and `aria-describedby` on `<Whisper>`
defaultOpen | boolean | Whether to open the overlay by default
delay | number | Delay time (ms) Time
delayClose | number | Delay close time (ms) Time
delayOpen | number | Delay open time (ms) Time
enterable | boolean | Whether mouse is allowed to enter the floating layer of popover, when the value of `trigger` is set to `hover`
followCursor | boolean | Whether enable `speaker` to follow the cursor
onBlur | () => void | Lose Focus callback function
onClick | () => void | Click on the callback function
onClose | () => void | Callback fired when close component
onEnter | () => void | Callback fired before the overlay transitions in
onEntered | () => void | Callback fired after the overlay finishes transitioning in
onEntering | () => void | Callback fired as the overlay begins to transition in
onExit | () => void | Callback fired right before the overlay transitions out
onExited | () => void | Callback fired after the overlay finishes transitioning out
onExiting | () => void | Callback fired as the overlay begins to transition out
onFocus | () => void | Callback function to get focus
onOpen | () => void | Callback fired when open component
open | boolean | Whether to open the overlay
placement | Placement `('right')` | Dispaly placement
preventOverflow | boolean | Prevent floating element overflow
speaker * | Tooltip | Popover | ReactElement | Displayed component
trigger | Trigger `(['hover','focus'])` | Triggering events
```

--------------------------------

### useMediaQuery Hook API

Source: https://rsuitejs.com/components/use-media-query

The useMediaQuery hook accepts a query or an array of queries and returns an array of booleans indicating whether the media query matches.

```APIDOC
## `useMediaQuery`

### Description
Use `useMediaQuery` to easily retrieve media dimensions, combined with the component's size property for responsive UI.

### Type Definition
```typescript
type Query =  'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | string

useMediaQuery(query: Query | Query[]) => boolean[]
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **boolean[]**: An array of booleans, where each boolean corresponds to a query in the input array and indicates whether the media query matches.

#### Response Example
```json
[
  true,
  false
]
```
```

--------------------------------

### useToaster() API

Source: https://rsuitejs.com/components/use-toaster

The useToaster hook provides methods to manage toast notifications. It returns an object with `push`, `remove`, and `clear` methods.

```APIDOC
## useToaster() API

### Description
Returns an object with the following methods:

### Methods
- **push** `(message: ReactNode, options?: ToastOptions) => string`: Display a toast message.
- **remove** `(toastId: string) => void`: Remove a message by ID.
- **clear** `() => void`: Remove all messages.
```

--------------------------------

### ToastOptions Type Definition

Source: https://rsuitejs.com/components/use-toaster

Defines the configuration options available for customizing toast notifications.

```APIDOC
## ToastOptions Type Definition

### Description
Configuration options for toast messages.

### Fields
- **container** `(HTMLElement | (() => HTMLElement))` - Optional - Set the container where the message appears. Defaults to `document.body`.
- **duration** `(number)` - Optional - The number of milliseconds to wait before automatically closing the message. Defaults to `4500`.
- **mouseReset** `(boolean)` - Optional - Reset the auto-close timer when the mouse enters the message. Defaults to `true`. (Available since v5.65.0)
- **placement** `('topCenter' | 'topStart' | 'topEnd' | 'bottomCenter' | 'bottomStart' | 'bottomEnd')` - Optional - Set the position of the message. Defaults to `'topCenter'`.
```

--------------------------------

### ToastOptions Interface Definition

Source: https://rsuitejs.com/components/use-toaster

Defines the configuration options for toast messages, including container, duration, mouse reset behavior, and placement. Defaults are provided for most options.

```typescript
interface ToastOptions {
  /**
   * Set the container where the message appears
   * @default document.body
   */
  container?: HTMLElement | (() => HTMLElement);

  /**
   * The number of milliseconds to wait before automatically closing the message
   * @default 4500
   */
  duration?: number;

  /**
   * Reset the auto-close timer when the mouse enters the message
   * @default true
   * @version 5.65.0
   */
  mouseReset?: boolean;

  /**
   * Set the position of the message
   * @default 'topCenter'
   */
  placement?: 'topCenter' | 'topStart' | 'topEnd' | 'bottomCenter' | 'bottomStart' | 'bottomEnd';
}
```

--------------------------------

### PromptOptions Type Definition

Source: https://rsuitejs.com/components/use-dialog

Defines options for a prompt dialog, including title, button texts, default value, validation function, and a close callback returning the input string.

```typescript
interface PromptOptions {
  title?: string; // Dialog title, defaults to 'Confirm'
  okText?: string; // Text for the OK button, defaults to 'OK'
  cancelText?: string; // Text for the Cancel button
  defaultValue?: string; // Default value for the input field
  validate?: (value: string) => [isValid: boolean, errorMessage?: string]; // Validation function
  onClose?: (result: string) => void; // Callback when dialog is closed
}
```

--------------------------------

### useMediaQuery API Definition

Source: https://rsuitejs.com/components/use-media-query

The useMediaQuery hook accepts a query string or an array of query strings and returns an array of booleans indicating whether each query matches.

```typescript
type Query =  'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | string

useMediaQuery(query: Query | Query[]) => boolean[]
```

--------------------------------

### OpenOptions Type Definition

Source: https://rsuitejs.com/components/use-dialog

Defines the options for opening a custom dialog, primarily including a callback function that is executed when the dialog is closed.

```typescript
interface OpenOptions<T> {
  onClose?: (result?: T) => void; // Callback when dialog is closed
}
```

--------------------------------

### AlertOptions Type Definition

Source: https://rsuitejs.com/components/use-dialog

Defines the options available for configuring an alert dialog, including title, OK button text, and a close callback.

```typescript
interface AlertOptions {
  title?: string; // Dialog title, defaults to 'Alert'
  okText?: string; // Text for the OK button, defaults to 'OK'
  onClose?: () => void; // Callback when dialog is closed
}
```

--------------------------------

### ConfirmOptions Type Definition

Source: https://rsuitejs.com/components/use-dialog

Defines the options for a confirmation dialog, including title, button texts, severity, and a close callback that receives the boolean result.

```typescript
interface ConfirmOptions {
  title?: string; // Dialog title, defaults to 'Confirm'
  okText?: string; // Text for the OK button, defaults to 'OK'
  cancelText?: string; // Text for the Cancel button
  severity?: 'info' | 'success' | 'warning' | 'error'; // Visual style of the dialog
  onClose?: (result: boolean) => void; // Callback when dialog is closed
}
```

--------------------------------

### Whisper Component - Type Definitions

Source: https://rsuitejs.com/components/whisper

Defines the types for `Trigger` and `Placement` used within the Whisper component.

```APIDOC
### Type definitions

#### `Trigger`

```typescript
type Trigger =
  | Array<'click' | 'contextMenu' | 'hover' | 'focus' | 'active'>
  | 'click'
  | 'contextMenu'
  | 'hover'
  | 'focus'
  | 'active'
  | 'none';
```

#### `Placement`

```typescript
type Placement =
  | 'top'
  | 'bottom'
  | 'right'
  | 'left'
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd'
  | 'auto'
  | 'autoVerticalStart'
  | 'autoVerticalEnd'
  | 'autoHorizontalStart'
  | 'autoHorizontalEnd';
```
```

--------------------------------

### Trigger Type Definition

Source: https://rsuitejs.com/components/whisper

TypeScript definition for the supported trigger events.

```typescript
type Trigger =
  | Array<'click' | 'contextMenu' | 'hover' | 'focus' | 'active'>
  | 'click'
  | 'contextMenu'
  | 'hover'
  | 'focus'
  | 'active'
  | 'none';
```
Tokens:
Raw