picospa.details
API for preserving the open/closed state of <details> elements across page loads.
reopen()
Method signature: reopen([{key?: string, nodes?: string[] | NodeList}])
Stores which details elements are open before page unload and reopens them on page load. The entire options object is optional. Can be called as:
reopen()- uses all defaultsreopen({key: 'custom'})- uses a custom keyreopen({nodes: customElements})- define which elements to trackreopen({key: 'custom', nodes: customElements})- uses custom key and custom elements
Parameters
key: string– The key used for storing in the session storage. Defaults to the value oflocation.pathnamewhich makes it unique per page.nodes: Array<string> | NodeList, optional– Either an array of CSS selectors or a NodeList fromdocument.querySelectorAll(). Defaults todocument.querySelectorAll('details')if not provided.
Description
The function sets up two main behaviors:
Storage (on beforeunload)
- For selector arrays: iterates through each selector and queries DOM using
document.querySelector() - For NodeList: directly accesses each element in the list
- Checks if each element has
openproperty set totrue - Collects either selectors (for arrays) or indices (for NodeList) for currently open details elements
- Stores data in sessionStorage using key format
${key} – dialog.reopen (selectors: NodeList|strings)
Restoration (immediate)
- Reads stored data from sessionStorage
- For selector arrays: joins selectors and uses
document.querySelectorAll()to find elements - For NodeList: directly accesses elements by stored indices
- Sets
open = trueon each found element
DOM Requirements
<details>elements must exist in the DOM and match provided selectors- Elements must have working
openproperty (standard HTML5 details behavior) - Page should be fully loaded when restoration occurs
Storage Details
- Uses
sessionStorage(persists only during browser session) - Storage key format:
${key} – dialog.reopen (selectors: NodeList|strings) - For selector arrays: stores as JSON array of selector strings:
["#faq1", ".expandable-section"] - For NodeList: stores as JSON array of indices:
[0, 2, 5] - Only tracks elements that are currently open (have
openattribute)
Example
// Using selector arrays
picospa.details.reopen('faq-page', [
'#frequently-asked-questions',
'#troubleshooting-section',
'.expandable-info'
]);
// Using NodeList
const detailsElements = document.querySelectorAll('details.collapsible');
picospa.details.reopen('interactive-sections', detailsElements);
// Without selectors - affects all details elements on the page
picospa.details.reopen('all-details');
// Cross-page navigation menu state
picospa.details.reopen({key: 'site-navigation', nodes: [
'#main-menu',
'#sidebar-sections'
]});
// Multiple selectors for flexible targeting
picospa.details.reopen({key: 'docs', nodes: [
'[data-section="api"]',
'[data-section="examples"]',
'details.collapsible'
]});
Selector Behavior
- Only tracks elements that match the provided selectors
- Non-matching
<details>elements are ignored - Missing elements during restoration are skipped silently
- Invalid selectors are filtered out during storage
Cross-Page Functionality
- Using the same
keyacross multiple pages preserves state during navigation - Useful for maintaining expanded menu/navigation states
- State persists within the browser session only
- Different pages can share state by using identical selectors and key
Error Handling
- Missing elements during storage/restoration are ignored
- Invalid selectors don't cause errors
- Malformed sessionStorage data defaults to empty array
- Non-details elements matching selectors are ignored
Browser Events
- Uses
beforeunloadevent for state capture - Executes restoration immediately when called
- Requires
sessionStoragesupport
Performance Notes
- Queries DOM once per selector during storage
- Single combined query during restoration for efficiency
- Storage operations are synchronous
- Minimal memory footprint (only stores selector strings)
autoOpen()
Method signature: autoOpen([{nodes?: string[] | NodeList}])
Automatically opens <details> elements that contain links matching the current page URL.
Parameters
nodes: (Array<string> | NodeList)- CSS selectors or NodeList of<details>elements to check
Description
- Iterates through each matching
<details>element - Searches within each element for
<a>tags withhrefattributes containing the currentlocation.pathname - Sets
open = trueon any<details>element containing matching links - Useful for navigation menus where sections should expand to show the current page
Example
// Auto-open all <details> elements that contain links to the current page
picospa.details.autoOpen();
// Auto-open navigation sections containing current page links
picospa.details.autoOpen({nodes: ['#navigation-menu', '.sidebar-sections']});
// Works with NodeList too
const menuElements = document.querySelectorAll('.nav-details');
picospa.details.autoOpen({nodes: menuElements});
// Combined usage with reopen
picospa.details.reopen({key: 'nav-state', nodes: ['#navigation']});
picospa.details.autoOpen({nodes: ['#navigation']});
Use Cases
- Navigation menus with hierarchical structure
- Sidebar sections containing page links
- Documentation sites with nested content organization
- Any expandable content that should indicate current location
Link Matching
- Matches any
<a href="...">where href contains the current pathname - Uses
location.pathnamefor comparison (excludes domain, query params, hash) - Partial matches are supported (e.g.,
/docs/apimatches links to/docs/api/methods)
DOM Requirements
- Must be called after DOM is fully loaded
- Target elements must be valid
<details>elements - Links must have
hrefattributes with pathname-based URLs
scrollOnOpen()
Method signature: scrollOnOpen([{nodes?: string[] | NodeList} | ScrollIntoViewOptions])
Scrolls the content of the <details> element(s) into view when toggled.
Can be called as:
scrollOnOpen()- uses all defaults, applies to all<details>elementsscrollOnOpen({nodes: ['.specific-details']})- define which elements to track, defined by a CSS selector arrayscrollOnOpen({nodes: document.querySelectorAll('.specific-details')})- defines the nodes using a NodeList (a result ofdocument.querySelectorAll())scrollOnOpen({behavior: 'smooth', block: 'start'})- uses custom scroll options on all<details>elements
Parameters
nodes: string[] | NodeList: Array of selectors or NodeList to target specific elements
Via the nodes option you can set which <details> elements should be scrolled into view when toggled.
behavior: default is'smooth'block: default is'start'inline: default is'nearest'
All the options other than nodes are
ScrollIntoViewOptions as the DOM method scrollIntoView()
method accepts them, they are just passed through.
Example
// Enable smooth scrolling for all <details> elements
picospa.details.scrollOnOpen();
// Or target specific elements
picospa.details.scrollOnOpen({
nodes: document.querySelectorAll('.collapsible-sections')
});
// Custom scroll behavior
picospa.details.scrollOnOpen({
behavior: 'smooth',
block: 'start',
inline: 'nearest'
});