spaish.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 defaults
• reopen({key: 'custom'}) - uses a custom key
• reopen({nodes: customElements}) - define which elements to track
• reopen({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 of location.pathname which makes it unique per page.
• nodes: Array<string> | NodeList, optional – Either an array of CSS selectors or a NodeList from document.querySelectorAll(). Defaults to document.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 open property set to true
• 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 = true on each found element

DOM Requirements

• <details> elements must exist in the DOM and match provided selectors
• Elements must have working open property (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 open attribute)

Example

// Using selector arrays
spaish.details.reopen('faq-page', [
  '#frequently-asked-questions',
  '#troubleshooting-section',
  '.expandable-info'
]);

// Using NodeList
const detailsElements = document.querySelectorAll('details.collapsible');
spaish.details.reopen('interactive-sections', detailsElements);

// Without selectors - affects all details elements on the page
spaish.details.reopen('all-details');

// Cross-page navigation menu state
spaish.details.reopen({key: 'site-navigation', nodes: [
  '#main-menu',
  '#sidebar-sections'
]});

// Multiple selectors for flexible targeting
spaish.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 key across 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 beforeunload event for state capture
• Executes restoration immediately when called
• Requires sessionStorage support

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 with href attributes containing the current location.pathname
• Sets open = true on 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
spaish.details.autoOpen();

// Auto-open navigation sections containing current page links
spaish.details.autoOpen({nodes: ['#navigation-menu', '.sidebar-sections']});

// Works with NodeList too
const menuElements = document.querySelectorAll('.nav-details');
spaish.details.autoOpen({nodes: menuElements});

// Combined usage with reopen
spaish.details.reopen({key: 'nav-state', nodes: ['#navigation']});
spaish.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.pathname for comparison (excludes domain, query params, hash)
• Partial matches are supported (e.g., /docs/api matches 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 href attributes with pathname-based URLs

scrollOnToggle()

Method signature: scrollOnToggle([{nodes?: string[] | NodeList} | ScrollIntoViewOptions])

Scrolls the content of the <details> element(s) into view when toggled. Can be called as:

• scrollOnToggle() - uses all defaults, applies to all <details> elements
• scrollOnToggle({nodes: ['.specific-details']}) - define which elements to track, defined by a CSS selector array
• scrollOnToggle({nodes: document.querySelectorAll('.specific-details')}) - defines the nodes using a NodeList (a result of document.querySelectorAll())
• scrollOnToggle({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
spaish.details.scrollOnToggle();
// Or target specific elements
spaish.details.scrollOnToggle({
  nodes: document.querySelectorAll('.collapsible-sections')
});
// Custom scroll behavior
spaish.details.scrollOnToggle({
  behavior: 'smooth',
  block: 'start',
  inline: 'nearest'
});