0
# Configuration and Styling
1

2
Comprehensive configuration options for customizing the appearance, behavior, and structure of the Collapsible component.
3

4
## Capabilities
5

6
### Element Structure Configuration
7

8
Configure the HTML structure and tag names used for different parts of the component.
9

10
```typescript { .api }
11
/**
12
 * Configure the HTML tag name for the root container element
13
 * @default "div"
14
 */
15
contentContainerTagName?: string;
16

17
/**
18
 * Configure the HTML tag name for the trigger element
19
 * @default "span"
20
 */
21
triggerTagName?: string;
22

23
/**
24
 * Pass additional props to the root container element
25
 * Useful for adding custom IDs, data attributes, or other HTML props
26
 */
27
containerElementProps?: object;
28

29
/**
30
 * Pass additional props to the trigger element
31
 * Useful for adding custom IDs, event handlers, or other HTML props
32
 */
33
triggerElementProps?: object;
34

35
/**
36
 * Custom ID for the content element
37
 * Auto-generated with timestamp if not provided
38
 */
39
contentElementId?: string;
40
```
41

42
**Usage Examples:**
43

44
```jsx
45
// Custom tag names and IDs
46
<Collapsible
47
  trigger="Expand"
48
  contentContainerTagName="section"
49
  triggerTagName="button"
50
  contentElementId="my-content-123"
51
  containerElementProps={{ 
52
    role: "region",
53
    "data-testid": "collapsible-section" 
54
  }}
55
  triggerElementProps={{ 
56
    "aria-label": "Toggle content visibility",
57
    type: "button"
58
  }}
59
>
60
  <p>Content here</p>
61
</Collapsible>
62
```
63

64
### State and Behavior Control
65

66
Control the component's open/closed state and interaction behavior.
67

68
```typescript { .api }
69
/**
70
 * Controls whether the collapsible is open or closed
71
 * When provided, component becomes controlled
72
 * @default false
73
 */
74
open?: boolean;
75

76
/**
77
 * Disables the trigger interaction
78
 * Prevents opening/closing when true
79
 * @default false
80
 */
81
triggerDisabled?: boolean;
82

83
/**
84
 * Delays rendering of content until first opened
85
 * Improves performance for expensive content
86
 * @default false
87
 */
88
lazyRender?: boolean;
89

90
/**
91
 * Adds HTML hidden attribute to content when closed
92
 * Improves accessibility by hiding content from screen readers
93
 * @default false
94
 */
95
contentHiddenWhenClosed?: boolean;
96

97
/**
98
 * Tab index for the trigger element
99
 * Controls keyboard navigation order
100
 */
101
tabIndex?: number;
102
```
103

104
**Usage Examples:**
105

106
```jsx
107
// Controlled component with disabled state
108
const [isOpen, setIsOpen] = useState(false);
109
const [isDisabled, setIsDisabled] = useState(false);
110

111
<Collapsible
112
  trigger="Controlled Collapsible"
113
  open={isOpen}
114
  triggerDisabled={isDisabled}
115
  lazyRender={true}
116
  contentHiddenWhenClosed={true}
117
  tabIndex={0}
118
  handleTriggerClick={() => setIsOpen(!isOpen)}
119
>
120
  <ExpensiveComponent />
121
</Collapsible>
122
```
123

124
### CSS Class Configuration
125

126
Comprehensive class name customization for styling at every level of the component.
127

128
```typescript { .api }
129
/**
130
 * Base CSS class prefix for all generated classes
131
 * @default "Collapsible"
132
 */
133
classParentString?: string;
134

135
/**
136
 * CSS class applied to root element when closed
137
 */
138
className?: string;
139

140
/**
141
 * CSS class applied to root element when open
142
 */
143
openedClassName?: string;
144

145
/**
146
 * CSS class applied to trigger element when closed
147
 */
148
triggerClassName?: string;
149

150
/**
151
 * CSS class applied to trigger element when open
152
 */
153
triggerOpenedClassName?: string;
154

155
/**
156
 * CSS class applied to outer content container
157
 */
158
contentOuterClassName?: string;
159

160
/**
161
 * CSS class applied to inner content container
162
 */
163
contentInnerClassName?: string;
164

165
/**
166
 * Inline styles applied to trigger element
167
 */
168
triggerStyle?: null | React.CSSProperties;
169
```
170

171
**Default CSS Classes Generated:**
172

173
The component automatically generates BEM-style CSS classes:
174

175
- **Root Element**: `.Collapsible` (plus custom `className`/`openedClassName`)
176
- **Trigger Element**: `.Collapsible__trigger` with state modifiers:
177
  - `.is-closed` / `.is-open` (state)
178
  - `.is-disabled` (when triggerDisabled is true)
179
- **Content Elements**: 
180
  - `.Collapsible__contentOuter` (outer container)
181
  - `.Collapsible__contentInner` (inner container)
182

183
**Usage Examples:**
184

185
```jsx
186
// Custom class configuration
187
<Collapsible
188
  trigger="Styled Collapsible"
189
  classParentString="MyCollapsible"
190
  className="collapsed-state"
191
  openedClassName="expanded-state"
192
  triggerClassName="my-trigger"
193
  triggerOpenedClassName="my-trigger--open"
194
  contentOuterClassName="my-content-outer"
195
  contentInnerClassName="my-content-inner"
196
  triggerStyle={{ fontWeight: 'bold', color: '#007acc' }}
197
>
198
  <div>Styled content</div>
199
</Collapsible>
200

201
// Results in classes like:
202
// .MyCollapsible.collapsed-state (when closed)
203
// .MyCollapsible.expanded-state (when open)
204
// .MyCollapsible__trigger.my-trigger.is-closed
205
// .MyCollapsible__contentOuter.my-content-outer
206
```
207

208
### Advanced Trigger Configuration
209

210
Advanced options for customizing trigger behavior and appearance.
211

212
```typescript { .api }
213
/**
214
 * Alternative trigger content displayed when component is open
215
 * Useful for "Show less" / "Show more" patterns
216
 */
217
triggerWhenOpen?: string | React.ReactElement<any>;
218

219
/**
220
 * Non-clickable element rendered next to the trigger
221
 * Can be a string, React element, or function that returns a React element
222
 * Useful for icons, badges, or additional information
223
 * @default null
224
 */
225
triggerSibling?: string | React.ReactElement<any> | (() => React.ReactElement<any>);
226

227
/**
228
 * Unique identifier when used in accordion patterns
229
 * Passed to handleTriggerClick callback
230
 */
231
accordionPosition?: string | number;
232
```
233

234
**Usage Examples:**
235

236
```jsx
237
// Dynamic trigger with sibling element
238
<Collapsible
239
  trigger="Show details"
240
  triggerWhenOpen="Hide details"
241
  triggerSibling={<span className="icon">📄</span>}
242
  accordionPosition="section-1"
243
>
244
  <div>Detailed information here</div>
245
</Collapsible>
246

247
// Function-based trigger sibling
248
<Collapsible
249
  trigger="Show details"
250
  triggerSibling={() => <span className="dynamic-icon">{isLoading ? '⏳' : '📄'}</span>}
251
>
252
  <div>Content with dynamic sibling</div>
253
</Collapsible>
254

255
// Accordion pattern
256
const accordionItems = [
257
  { id: 'item1', title: 'First Item', content: 'Content 1' },
258
  { id: 'item2', title: 'Second Item', content: 'Content 2' }
259
];
260

261
{accordionItems.map((item, index) => (
262
  <Collapsible
263
    key={item.id}
264
    trigger={item.title}
265
    accordionPosition={index}
266
    handleTriggerClick={(position) => {
267
      console.log(`Clicked accordion item at position: ${position}`);
268
    }}
269
  >
270
    <div>{item.content}</div>
271
  </Collapsible>
272
))}
273
```