Skip to content

Commit 4ee2e5e

Browse files
athphaneathphane
committed
docs: expand accordion component documentation
1 parent 4a9b1ad commit 4ee2e5e

1 file changed

Lines changed: 175 additions & 46 deletions

File tree

‎docs/basic-usage/accordion.md‎

Lines changed: 175 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -3,81 +3,210 @@ title: Accordion
33
sidebar_position: 10
44
---
55

6-
You can use the `accordion` component to render JavaScript accordion. The `accordion` component requires an array or Collection of items. The content for each item can be passed as named slots with the slot names same as the key of the item in kebab case. If you want to add html content to the item header, you can use the `{item-slot-name}-header` slot to provide the content for that item's header.
6+
The `accordion` component groups content into collapsible panels. It supports Bootstrap 5 and Material Admin 2.6 and can render items from an array or Collection, or from components in its default slot.
77

8+
## Basic Usage
89

9-
```bladehtml
10+
Provide a unique `id` for the accordion and pass an array or Collection to `items`.
11+
12+
```html
1013
@php
11-
$items = [
12-
'collapseOne' => ['show' => true, 'id' => 'item-1'],
13-
'collapseTwo' => ['title' => 'Accordion Item #2', 'id' => 'item-2', 'content' => 'Second item Body']
14-
]
14+
$items = [
15+
'applicationRequirements' => [
16+
'title' => 'What do I need to apply?',
17+
'content' => 'Have your identification and supporting documents ready.',
18+
'show' => true,
19+
],
20+
'applicationStatus' => [
21+
'title' => 'How do I check my application status?',
22+
'content' => 'Sign in and open the applications page.',
23+
],
24+
];
1525
@endphp
1626

17-
<x-forms::accordion id="accordionExample" :items="$items">
18-
<x-slot:collapse-one-header>
19-
Accordion Item #1
20-
</x-slot:collapse-one-header>
27+
<x-forms::accordion id="application-faq" :items="$items" />
28+
```
29+
30+
The first panel starts open because its `show` value is `true`. Panels default to closed; the component does not automatically open the first item.
31+
32+
Opening and closing panels requires the Bootstrap collapse JavaScript used by your theme. Load it in your application layout; the component generates the markup without loading JavaScript itself.
33+
34+
### Item Options
35+
36+
Each entry in `items` accepts these keys:
37+
38+
| Key | Default | Description |
39+
| --- | --- | --- |
40+
| `title` | `''` | Header text. A header slot takes precedence. No title is generated from the item key. |
41+
| `content` | `''` | Body text. A body slot takes precedence. HTML is escaped and line breaks are converted to `<br>` tags. |
42+
| `show` | `false` | Whether the panel is initially expanded. |
43+
| `id` | Not set | Optional ID for the item wrapper, separate from the collapsible panel's ID. |
44+
45+
### Panel IDs
46+
47+
For named items, the array key becomes the panel ID, with spaces replaced by hyphens. In the example above, the panels have IDs `applicationRequirements` and `applicationStatus`.
48+
49+
For numeric keys, the panel ID is `{accordion-id}-item-{key}-collapse`. For example, key `0` inside `application-faq` produces `application-faq-item-0-collapse`.
50+
51+
Keep panel IDs unique across the page. Named keys are not prefixed with the accordion ID, so use different keys when rendering multiple accordions. Setting an item's `id` changes its wrapper ID, not its panel ID.
2152

22-
<x-slot:collapse-one>
23-
<strong>First item Body</strong>
24-
</x-slot:collapse-one>
53+
## Custom Headers and Content
54+
55+
Use named slots when headers or bodies need HTML. For a named item, use its key in kebab case for the body slot and append `-header` for the header slot. For example, `applicationRequirements` uses `application-requirements` and `application-requirements-header`.
56+
57+
```html
58+
@php
59+
$items = [
60+
'applicationRequirements' => ['show' => true, 'id' => 'requirements-item'],
61+
'applicationStatus' => [
62+
'title' => 'Checking your status',
63+
'content' => 'Sign in to view your application status.',
64+
],
65+
];
66+
@endphp
67+
68+
<x-forms::accordion id="application-faq" :items="$items">
69+
<x-slot:application-requirements-header>
70+
<strong>Required documents</strong>
71+
</x-slot:application-requirements-header>
72+
73+
<x-slot:application-requirements>
74+
<p>Please prepare the following documents:</p>
75+
<ul>
76+
<li>Identification</li>
77+
<li>Proof of address</li>
78+
</ul>
79+
</x-slot:application-requirements>
2580
</x-forms::accordion>
2681
```
2782

28-
The accordion items support the following values:
29-
- `'show'` - Whether to have the item open or not.
30-
- `'title'` - Title for the item
31-
- `'content'` - Content for the item
32-
- `'id''` - The css id for the item
83+
A body slot replaces the corresponding item's `content`, and a non-empty header slot replaces its `title`.
3384

34-
If your items array is not associative, the slots name for each item will be `item-{index}`.
85+
### Numeric Item Keys
3586

36-
```bladehtml
87+
For a list with numeric keys, use `item-{key}` and `item-{key}-header` slots. Keys are used as supplied, rather than renumbered by position.
88+
89+
```html
3790
@php
3891
$items = [
39-
['show' => true, 'id' => 'item-1'],
40-
['title' => 'Accordion Item #2', 'id' => 'item-2']
41-
]
92+
['title' => 'Required documents', 'show' => true],
93+
['title' => 'Next steps', 'content' => 'Submit your application for review.'],
94+
];
4295
@endphp
4396

44-
<x-forms::accordion id="accordionExample" :items="$items">
97+
<x-forms::accordion id="application-faq" :items="$items">
4598
<x-slot:item-0-header>
46-
Accordion Item #1
99+
<strong>Before you apply</strong>
47100
</x-slot:item-0-header>
48101

49102
<x-slot:item-0>
50-
<strong>First item Body</strong>
103+
<p>Have your identification ready.</p>
51104
</x-slot:item-0>
52-
53-
<x-slot:item-1>
54-
<strong>Second item Body</strong>
55-
</x-slot:item-1>
56105
</x-forms::accordion>
57106
```
58107

59-
Without passing an items array, you can manually create accordion items using the `accordion.item` component as well.
108+
## Creating Items Manually
109+
110+
Omit `items` and place `accordion.item` components in the default slot. Each item requires a `name` for its panel ID and a `parent` matching the accordion ID, without a leading `#`.
60111

61-
```bladehtml
62-
<x-forms::accordion id="accordionExample">
63-
<x-forms::accordion.item id="item-1" name="collapseOne" parent="accordionExample" show>
112+
```html
113+
<x-forms::accordion id="application-faq">
114+
<x-forms::accordion.item
115+
id="requirements-item"
116+
name="applicationRequirements"
117+
parent="application-faq"
118+
show
119+
>
64120
<x-slot:header>
65-
Accordion Item #1
121+
<strong>Required documents</strong>
66122
</x-slot:header>
67123

68-
<strong>First item Body</strong>
124+
<p>Have your identification ready.</p>
69125
</x-forms::accordion.item>
70126

71-
<x-forms::accordion.item id="item-2" name="collapseTwo" parent="accordionExample" :show="false" title="Accordion Item #2">
72-
<strong>Second item Body</strong>
73-
</x-forms::accordion.item>
127+
<x-forms::accordion.item
128+
name="applicationStatus"
129+
parent="application-faq"
130+
title="Checking your status"
131+
content="Sign in to view your application status."
132+
:show="false"
133+
/>
134+
</x-forms::accordion>
135+
```
136+
137+
The item's `header` slot takes precedence over `title`. For a manually created item, a non-empty `content` attribute takes precedence over the default body slot. Use the default slot for HTML and leave `content` empty.
138+
139+
The accordion's default slot is rendered after any generated items, so you can also combine an `items` array with manually created items.
140+
141+
### Accordion Options
142+
143+
| Attribute | Type | Default | Description |
144+
| --- | --- | --- | --- |
145+
| `id` | `string` | **Required** | ID of the outer accordion and the parent used by generated panels. |
146+
| `items` | `array` or `Collection` | `[]` | Items to render. Omit when creating items in the default slot. |
147+
| `framework` | `string` | `''` | Uses `forms.framework` when omitted. Supports `bootstrap-5` and `material-admin-26`. |
148+
149+
### Accordion Item Options
150+
151+
| Attribute | Type | Default | Description |
152+
| --- | --- | --- | --- |
153+
| `name` | `string` | **Required** | ID of the collapsible panel, also used as the header's target. |
154+
| `parent` | `string` | **Required** | ID of the parent accordion, without `#`. |
155+
| `title` | `string` | `''` | Header text when no non-empty `header` slot is provided. |
156+
| `content` | `string` | `''` | Body text, escaped with line breaks preserved. When non-empty, overrides the default slot. |
157+
| `show` | `bool` | `false` | Sets the initial expanded state of both the header and panel. |
158+
| `framework` | `string` | `''` | Uses `forms.framework` when omitted. |
159+
160+
## Separate Header and Collapse Components
161+
162+
For a custom item layout, use `accordion.header` and `accordion.collapse` directly. Match the header's `target` to the collapse element's `id`, and use the same `show` value on both.
163+
164+
```html
165+
<x-forms::accordion id="custom-faq">
166+
<div class="accordion-item">
167+
<x-forms::accordion.header target="custom-requirements" show>
168+
Required documents
169+
</x-forms::accordion.header>
170+
171+
<x-forms::accordion.collapse id="custom-requirements" parent="custom-faq" show>
172+
<p>Have your identification ready.</p>
173+
</x-forms::accordion.collapse>
174+
</div>
74175
</x-forms::accordion>
75176
```
76177

77-
The `accordion.item` component supports the following attributes.
78-
- `name` - (Required) Name of the item. This will be used for the collpase id.
79-
- `parent` - (Required) CSS id of the parent accordion.
80-
- `title` - Title for the item. Title can be passed through the `header` slot as well if HTML content is needed in the title.
81-
- `content` - Content for the item. Content can be passed through the main slot as well if HTML content is needed.
82-
- `show` - Whether to have the item open or not
83-
- `framework` - Which css framework to use.
178+
This example uses Bootstrap 5's item wrapper class. For Material Admin 2.6, use `accordion__item` on the wrapper.
179+
180+
### Header Options
181+
182+
| Attribute | Type | Default | Description |
183+
| --- | --- | --- | --- |
184+
| `target` | `string` | **Required** | ID of the panel to toggle, without `#`. |
185+
| `title` | `string` | `''` | Header text when the default slot is empty. |
186+
| `show` | `bool` | `false` | Initial `aria-expanded` state. Match the panel's `show` value. |
187+
| `framework` | `string` | `''` | Uses `forms.framework` when omitted. |
188+
189+
### Collapse Options
190+
191+
| Attribute | Type | Default | Description |
192+
| --- | --- | --- | --- |
193+
| `parent` | `string` | **Required** | ID of the parent accordion, without `#`. |
194+
| `content` | `string` | `''` | Body text, escaped with line breaks preserved. When non-empty, overrides the default slot. |
195+
| `show` | `bool` | `false` | Adds the `show` class to initially expand the panel. |
196+
| `framework` | `string` | `''` | Uses `forms.framework` when omitted. |
197+
198+
Set the collapse element's `id` as an HTML attribute; the collapse component does not generate one itself.
199+
200+
## Frameworks and HTML Attributes
201+
202+
Generated items inherit the accordion's `framework`. When creating items or separate header and collapse components manually, pass the same `framework` to each if you are overriding the configured default.
203+
204+
Bootstrap 5 uses `data-bs-toggle`, `data-bs-target`, and `data-bs-parent` for collapse behavior. Material Admin 2.6 uses `data-toggle`, `data-target`, and `data-parent`. Load the matching theme styles and JavaScript.
205+
206+
Additional HTML attributes are passed to the outer element of each component. Classes are merged with the component's default classes.
207+
208+
```html
209+
<x-forms::accordion id="application-faq" :items="$items" class="mb-4" data-section="faq" />
210+
```
211+
212+
See [Installation & Setup](../installation-and-setup.md) to configure the default framework or publish the component views.

0 commit comments

Comments
 (0)