Disclosure

Show and hide content when a user clicks, taps, or activates a <button> with the <kelp-disclosure> web component.

Usage

Wrap a <button> in a <kelp-disclosure> element, and add a [target] attribute whose value is the ID of the content the <button> should show and hide.

<kelp-disclosure target="#content">
	<button>Toggle Content</button>
</kelp-disclosure>

<div id="content">
	Now you see me, now you don't!
</div>

The <kelp-disclosure> component adds all of the ARIA attributes and keyboard and focus behaviors required for an accessible component.

Dropdown Menu

The <kelp-disclosure> component can be used to display a dropdown menu by adding an [is-dropdown] attribute.

Your dropdown menu must be an unordered list (<ul>), and must be nested inside the <kelp-disclosure> element. You can omit the [target] attribute.

<kelp-disclosure is-dropdown>
	<button >Toggle Content</button>
	<ul>
		<li>Now you see me...</li>
		<li>Now you don't!</li>
		<li><a href="#">With a link</a></li>
		<li><button>With a button</button></li>
	</ul>
</kelp-disclosure>

Dropdown menus automatically close when the user interacts with any element outside of the dropdown or presses the Escape key.

Menu Alignment

By default, dropdown menus are positioned 0.125em (about 2px) below the toggling <button>, and aligned to the inline start (the left side in LTR languages).

You can align the dropdown menu with the inline end (the right side in LRT languages) by adding the .dropdown-end class to the unordered list (<ul>).

<kelp-disclosure is-dropdown>
	<button >Toggle Content</button>
	<ul class="dropdown-end">
		<!-- ... -->
	</ul>
</kelp-disclosure>

You can adjust the space between the menu and the <button> by modifying the --gap on the <kelp-disclosure> component. You can do this with one of the .gap-* classes, or with an inline [style] attribute.

<kelp-disclosure is-dropdown class="gap-xs">
	<!-- ... -->
</kelp-disclosure>

<kelp-disclosure is-dropdown style="--gap: 1px">
	<!-- ... -->
</kelp-disclosure>

Fallback Content

Because disclosure buttons and dropdown menu content are not usuable until JavaScript is ready, the <kelp-disclosure> component pairs nicely with the [hide-until-ready] and [show-until-ready] attributes.

For simple disclosure components, the [hide-until-ready] attribute alone is sufficient. Content will be visible until it loads.

<kelp-disclosure target="#content" hide-until-ready>
	<button>Toggle Content</button>
</kelp-disclosure>

For dropdown menus, you can add a fallback URL or navigation pattern with the [show-until-ready] attribute.

<kelp-disclosure is-dropdown hide-until-ready>
	<a 
		href="/path/to/fallback/content"
		show-until-ready
	>Learn more</a>
	<button >Toggle Content</button>
	<ul>
		<li>Now you see me...</li>
		<li>Now you don't!</li>
		<li><a href="#">With a link</a></li>
		<li><button>With a button</button></li>
	</ul>
</kelp-disclosure>

This ensures a more resilient and accessible experience.

Events

The <kelp-disclosure> element emits a few events.

• kelp-disclosure:ready emits when the component is instantiated.
• kelp-disclosure:show-before emits before content is shown.
  • cancelable - you can stop the content from being shown by running event.preventDefault().
• kelp-disclosure:show emits after content is shown.
• kelp-disclosure:hide-before emits before content is hidden.
  • cancelable - you can stop the content from being hidden by running event.preventDefault().
• kelp-disclosure:hide emits after content is hidden.

document.addEventListener('kelp-disclosure:ready', (event) => {
	console.log('ready:', event.target);
});

document.addEventListener('kelp-disclosure:show-before', (event) => {
	console.log('A disclosure is about to show content:', event.target);

	// Stop this from happening
	event.preventDefault();
});

document.addEventListener('kelp-disclosure:show', (event) => {
	console.log('Content was shown:', event.target);
});

document.addEventListener('kelp-disclosure:hide-before', (event) => {
	console.log('A disclosure is about to hide content:', event.target);

	// Stop this from happening
	event.preventDefault();
});

document.addEventListener('kelp-disclosure:hide', (event) => {
	console.log('Content was hidden:', event.target);
});

Methods

While web components are self-instantiating, the <kelp-disclosure> element has a few methods you can manually run if needed.

• .show() - Show the content controlled by the disclosure.
• .hide() - Hide the content controlled by the disclosure.
• .toggle() - Toggle visibility of the content controlled by the disclosure (show content if hidden, hide content if shown).
• .init() - Manually initialize the component, if it fails for some reason.

const disclosure = document.querySelector('kelp-disclosure');

// Show the controlled content
disclosure.show();

// Hide the controlled content
disclosure.hide();

// Toggle content visibility
disclosure.toggle();