feat(Accordion/Collapsible): hiddenUntilFound prop (#1782)

Author: huntabyte

.changeset/funny-boats-roll.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+feat(Collapsible): add `hiddenUntilFound` prop to expand collapsible when the content matches a browser search

.changeset/yellow-eagles-itch.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+feat(Accordion): `hiddenUntilFound` to expand on browser search match

docs/content/components/accordion.md

@@ -270,6 +270,25 @@ Disable specific items with the `disabled` prop:
 </Accordion.Root>
 ```
 
+### Hidden Until Found
+
+The `hiddenUntilFound` prop enables browser search functionality within collapsed accordion content. When enabled, collapsed content is marked with `hidden="until-found"`, allowing browsers to automatically expand accordion items when users search for text within them.
+
+```svelte {4}
+<Accordion.Root type="single">
+  <Accordion.Item value="item-1">
+    <Accordion.Header>
+      <Accordion.Trigger>Search Demo</Accordion.Trigger>
+    </Accordion.Header>
+    <Accordion.Content hiddenUntilFound>
+      This content can be found by browser search (Ctrl+F/CMD+F) even when the
+      accordion is closed. The accordion will automatically open when the
+      browser finds matching text.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion.Root>
+```
+
 ### Svelte Transitions
 
 The Accordion component can be enhanced with Svelte's built-in transition effects or other animation libraries.

docs/content/components/collapsible.md

@@ -4,7 +4,7 @@ description: Conceals or reveals content sections, enhancing space utilization a
 ---
 
 <script>
-	import { APISection, ComponentPreview, CollapsibleDemo, CollapsibleDemoTransitions, Callout } from '$lib/components/index.js'
+	import { APISection, ComponentPreview, CollapsibleDemo, CollapsibleDemoTransitions, CollapsibleHiddenUntilFoundDemo, Callout } from '$lib/components/index.js'
 	let { schemas } = $props()
 </script>
 
@@ -26,6 +26,7 @@ The Collapsible component enables you to create expandable and collapsible conte
 - **Transition Support**: CSS variables and data attributes for smooth transitions between states.
 - **Flexible State Management**: Supports controlled and uncontrolled state, take control if needed.
 - **Compound Component Structure**: Provides a set of sub-components that work together to create a fully-featured collapsible.
+- **Hidden Until Found**: Support for the `hidden="until-found"` attribute for browser search integration.
 
 ## Architecture
 
@@ -218,4 +219,37 @@ You can then use the `MyCollapsibleContent` component alongside the other `Colla
 </Collapsible.Root>
 ```
 
+## Hidden Until Found
+
+The `hiddenUntilFound` prop enables integration with the browser's find-in-page functionality. When enabled, the collapsible content is marked with `hidden="until-found"`, which allows browsers to automatically expand collapsed content when users search for text within it.
+
+<ComponentPreview variant="collapsed" name="collapsible-hidden-until-found-demo" componentName="Collapsible">
+
+{#snippet preview()}
+<CollapsibleHiddenUntilFoundDemo />
+{/snippet}
+
+</ComponentPreview>
+
+### Basic Usage
+
+```svelte
+<script lang="ts">
+  import { Collapsible } from "bits-ui";
+</script>
+
+<Collapsible.Root>
+  <Collapsible.Trigger>Show More Details</Collapsible.Trigger>
+  <Collapsible.Content hiddenUntilFound={true}>
+    <p>
+      This content will be automatically revealed when users search for text
+      within it using Ctrl+F (Cmd+F on Mac).
+    </p>
+    <p>
+      For example, try searching for "automatically revealed" on this page.
+    </p>
+  </Collapsible.Content>
+</Collapsible.Root>
+```
+
 <APISection {schemas} />

docs/src/lib/components/demos/collapsible-demo.svelte

@@ -14,7 +14,10 @@
 		</Collapsible.Trigger>
 	</div>
 
-	<Collapsible.Content class="space-y-2 font-mono text-[15px] tracking-[0.01em]">
+	<Collapsible.Content
+		hiddenUntilFound
+		class="data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up space-y-2 overflow-hidden font-mono text-[15px] tracking-[0.01em]"
+	>
 		<div class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3">
 			@huntabyte/bits-ui
 		</div>

docs/src/lib/components/demos/collapsible-hidden-until-found-demo.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import { Collapsible } from "bits-ui";
+	import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
+</script>
+
+<div class="flex w-full max-w-md flex-col gap-4">
+	<div
+		class="border-border bg-background-alt absolute left-4 top-4 flex flex-col gap-2 rounded-xl border p-4"
+	>
+		<div class="text-foreground-alt flex flex-col gap-2 text-sm">
+			<span>Try searching for "searchable content" on this page</span>
+			<code class="bg-muted w-fit rounded px-1 py-0.5 text-xs">(Ctrl+F / Cmd+F)</code>
+		</div>
+	</div>
+
+	<Collapsible.Root class="flex flex-col gap-3">
+		<div class="flex items-center justify-between gap-4">
+			<h4 class="text-[15px] font-medium">FAQ: How does search work?</h4>
+			<Collapsible.Trigger
+				class="rounded-9px border-border-input bg-background-alt text-foreground shadow-btn hover:bg-muted inline-flex h-10 w-10 items-center justify-center border transition-all active:scale-[0.98]"
+				aria-label="Toggle FAQ answer"
+			>
+				<CaretUpDown class="size-4" weight="bold" />
+			</Collapsible.Trigger>
+		</div>
+
+		<Collapsible.Content
+			hiddenUntilFound
+			class="data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up overflow-hidden"
+		>
+			<div
+				class="bg-background border-border rounded-lg border p-4 text-[14px] leading-relaxed"
+			>
+				<p class="mb-3">
+					This collapsible contains <strong>searchable content</strong> that demonstrates
+					the
+					<code class="bg-muted rounded px-1 py-0.5 text-xs">hiddenUntilFound</code> feature.
+					When you search for text within this collapsed section, the browser will automatically
+					expand it to show the matching results.
+				</p>
+			</div>
+		</Collapsible.Content>
+	</Collapsible.Root>
+</div>

docs/src/lib/components/demos/index.ts

@@ -16,6 +16,7 @@ export { default as CheckboxDemoCustom } from "./checkbox-demo-custom.svelte";
 export { default as CheckboxDemoGroup } from "./checkbox-demo-group.svelte";
 export { default as CollapsibleDemo } from "./collapsible-demo.svelte";
 export { default as CollapsibleDemoTransitions } from "./collapsible-demo-transitions.svelte";
+export { default as CollapsibleHiddenUntilFoundDemo } from "./collapsible-hidden-until-found-demo.svelte";
 export { default as ComboboxDemo } from "./combobox-demo.svelte";
 export { default as ComboboxDemoAutoScrollDelay } from "./combobox-demo-auto-scroll-delay.svelte";
 export { default as ComboboxDemoTransition } from "./combobox-demo-transition.svelte";

docs/src/lib/content/api-reference/accordion.api.ts

@@ -131,6 +131,11 @@ const content = defineComponentApiSchema<AccordionContentPropsWithoutHTML>({
 	description: "The accordion item content, which is displayed when the item is open.",
 	props: {
 		forceMount: forceMountProp,
+		hiddenUntilFound: defineBooleanProp({
+			description:
+				"Whether the content should use `hidden='until-found'` when closed. This allows browsers to search within collapsed content and automatically expand the accordion item when matches are found.",
+			default: false,
+		}),
 		...withChildProps({
 			elType: "HTMLDivElement",
 			child: {

docs/src/lib/content/api-reference/collapsible.api.ts

@@ -84,6 +84,11 @@ export const content = defineComponentApiSchema<CollapsibleContentPropsWithoutHT
 	description: "The content displayed when the collapsible is open.",
 	props: {
 		forceMount: forceMountProp,
+		hiddenUntilFound: defineBooleanProp({
+			default: false,
+			description:
+				'When true, the content will be marked with `hidden="until-found"` when collapsed, allowing browsers to find and automatically expand the content during page searches.',
+		}),
 		...withChildProps({
 			elType: "HTMLDivElement",
 			child: {

docs/src/lib/styles/app.css

@@ -132,6 +132,8 @@
 
 	--animate-accordion-down: accordion-down 0.2s ease-out;
 	--animate-accordion-up: accordion-up 0.2s ease-out;
+	--animate-collapsible-down: collapsible-down 0.2s ease-out;
+	--animate-collapsible-up: collapsible-up 0.2s ease-out;
 	--animate-caret-blink: caret-blink 1s ease-out infinite;
 	--animate-scale-in: scale-in 0.2s ease;
 	--animate-scale-out: scale-out 0.15s ease;
@@ -167,6 +169,27 @@
 		}
 	}
 
+	@keyframes collapsible-down {
+		from {
+			height: 0;
+		}
+
+		to {
+			height: var(--bits-collapsible-content-height);
+		}
+	}
+
+	@keyframes collapsible-up {
+		from {
+			height: var(--bits-collapsible-content-height);
+		}
+
+		to {
+			height: 0;
+		}
+	}
+
+
 	@keyframes caret-blink {
 
 		0%,