0
# Interactive Components
1

2
Interactive components provide user interface elements for actions, selections, and user interactions with consistent styling and accessibility support.
3

4
## Capabilities
5

6
### Button
7

8
Primary action component for triggering operations, form submissions, and navigation with support for different variants, sizes, and loading states.
9

10
```typescript { .api }
11
/**
12
 * Button component props extending HTML button attributes
13
 */
14
interface ButtonProps {
15
  /** Button content */
16
  children?: React.ReactNode;
17
  /** Button visual variant */
18
  variant?: "solid" | "bordered" | "light" | "flat" | "faded" | "shadow" | "ghost";
19
  /** Button size */
20
  size?: "sm" | "md" | "lg";
21
  /** Button color theme */
22
  color?: "default" | "primary" | "secondary" | "success" | "warning" | "danger";
23
  /** Border radius */
24
  radius?: "none" | "sm" | "md" | "lg" | "full";
25
  /** Whether button takes full width */
26
  fullWidth?: boolean;
27
  /** Whether button is disabled */
28
  isDisabled?: boolean;
29
  /** Whether button shows loading state */
30
  isLoading?: boolean;
31
  /** Whether button is icon-only (for spacing adjustments) */
32
  isIconOnly?: boolean;
33
  /** Content displayed at start of button */
34
  startContent?: React.ReactNode;
35
  /** Content displayed at end of button */
36
  endContent?: React.ReactNode;
37
  /** Custom spinner element for loading state */
38
  spinner?: React.ReactNode;
39
  /** Placement of spinner when loading */
40
  spinnerPlacement?: "start" | "end";
41
  /** Whether to disable ripple effect */
42
  disableRipple?: boolean;
43
  /** Whether to disable animations */
44
  disableAnimation?: boolean;
45
  /** Custom CSS classes */
46
  className?: string;
47
  /** Custom CSS classes for different component slots */
48
  classNames?: SlotsToClasses<ButtonSlots>;
49
  /** Press event handler (preferred over onClick) */
50
  onPress?: (e: PressEvent) => void;
51
  /** Press start event handler */
52
  onPressStart?: (e: PressEvent) => void;
53
  /** Press end event handler */
54
  onPressEnd?: (e: PressEvent) => void;
55
  /** Press change event handler */
56
  onPressChange?: (isPressed: boolean) => void;
57
  /** Press up event handler */
58
  onPressUp?: (e: PressEvent) => void;
59
}
60

61
function Button(props: ButtonProps): JSX.Element;
62

63
type ButtonSlots = "base";
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { Button } from "@nextui-org/react";
70

71
// Basic button
72
<Button color="primary">
73
  Click me
74
</Button>
75

76
// Button with loading state
77
<Button isLoading color="secondary">
78
  Loading...
79
</Button>
80

81
// Button with start/end content
82
<Button 
83
  startContent={<IconUser />}
84
  endContent={<IconArrow />}
85
  variant="bordered"
86
>
87
  Profile
88
</Button>
89

90
// Icon-only button
91
<Button isIconOnly variant="light" aria-label="Settings">
92
  <IconSettings />
93
</Button>
94

95
// Full-width button
96
<Button fullWidth color="success">
97
  Submit Form
98
</Button>
99
```
100

101
### Button Variants
102

103
NextUI Button supports multiple visual styles through the variant prop:
104

105
- **solid**: Filled background with solid color (default)
106
- **bordered**: Transparent background with colored border
107
- **light**: Subtle background with transparent hover states
108
- **flat**: Subtle filled background
109
- **faded**: Semi-transparent background with border
110
- **shadow**: Solid background with shadow effect
111
- **ghost**: Transparent with border that appears on hover
112

113
### ButtonGroup
114

115
Container component for grouping multiple related buttons together with consistent spacing and visual connections.
116

117
```typescript { .api }
118
interface ButtonGroupProps {
119
  /** Button group content */
120
  children: React.ReactNode;
121
  /** Size applied to all child buttons */
122
  size?: "sm" | "md" | "lg";
123
  /** Color applied to all child buttons */
124
  color?: "default" | "primary" | "secondary" | "success" | "warning" | "danger";
125
  /** Variant applied to all child buttons */
126
  variant?: "solid" | "bordered" | "light" | "flat" | "faded" | "shadow" | "ghost";
127
  /** Border radius applied to the group */
128
  radius?: "none" | "sm" | "md" | "lg" | "full";
129
  /** Whether the group should take full width */
130
  fullWidth?: boolean;
131
  /** Whether the group is disabled */
132
  isDisabled?: boolean;
133
  /** Whether to disable animations */
134
  disableAnimation?: boolean;
135
  /** Whether to disable ripple effects */
136
  disableRipple?: boolean;
137
  /** Custom CSS classes */
138
  className?: string;
139
  /** Custom CSS classes for different component slots */
140
  classNames?: SlotsToClasses<ButtonGroupSlots>;
141
}
142

143
function ButtonGroup(props: ButtonGroupProps): JSX.Element;
144

145
type ButtonGroupSlots = "base";
146
```
147

148
**Usage Example:**
149

150
```typescript
151
import { Button, ButtonGroup } from "@nextui-org/react";
152

153
<ButtonGroup variant="bordered" size="sm">
154
  <Button>One</Button>
155
  <Button>Two</Button>
156
  <Button>Three</Button>
157
</ButtonGroup>
158
```
159

160
## Types
161

162
```typescript { .api }
163
// Press event from React Aria
164
interface PressEvent {
165
  /** The type of press event being fired */
166
  type: 'pressstart' | 'pressend' | 'pressup' | 'press';
167
  /** The pointer type that triggered the press event */
168
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
169
  /** The target element of the press event */
170
  target: Element;
171
  /** Whether the shift keyboard modifier was held during the press event */
172
  shiftKey: boolean;
173
  /** Whether the ctrl keyboard modifier was held during the press event */
174
  ctrlKey: boolean;
175
  /** Whether the meta keyboard modifier was held during the press event */
176
  metaKey: boolean;
177
  /** Whether the alt keyboard modifier was held during the press event */
178
  altKey: boolean;
179
}
180

181
// Slot-based styling system
182
type SlotsToClasses<S extends string> = {
183
  [key in S]?: string;
184
};
185
```