BitsConfig

Utilities

Local guide ↗ import { BitsConfig } from "bits-ui"

Inherited defaults

A nested provider inherits the parent locale while overriding only its portal target

Parent target

#config-parent-target

Child target

#config-child-target

Parent config

locale: fr-FR
portal target: #config-parent-target

Nested config

locale: fr-FR
portal target: #config-child-target

The nested scope inherits fr-FR, but its Portal resolves to the nearer target override.

<script lang="ts">
	import { BitsConfig, Portal } from 'bits-ui';
	import ConfigProbe from './ConfigProbe.svelte';
</script>

<div class="grid gap-4">
	<div class="grid gap-3 sm:grid-cols-2">
		<section class="panel min-h-24 p-3">
			<div class="mb-2 flex items-center justify-between gap-2">
				<p class="text-xs font-semibold tracking-wider text-ink-200 uppercase">Parent target</p>
				<code class="chip">#config-parent-target</code>
			</div>
			<div id="config-parent-target" class="grid min-h-12 place-items-center rounded-lg border border-dashed border-ink-700 p-2"></div>
		</section>

		<section class="panel min-h-24 p-3">
			<div class="mb-2 flex items-center justify-between gap-2">
				<p class="text-xs font-semibold tracking-wider text-ink-200 uppercase">Child target</p>
				<code class="chip">#config-child-target</code>
			</div>
			<div id="config-child-target" class="grid min-h-12 place-items-center rounded-lg border border-dashed border-brand-500/40 p-2"></div>
		</section>
	</div>

	<BitsConfig defaultLocale="fr-FR" defaultPortalTo="#config-parent-target">
		<div class="grid gap-3 sm:grid-cols-2">
			<div class="grid gap-3">
				<ConfigProbe label="Parent config" />
				<Portal>
					<div class="panel animate-pop-in px-3 py-2 text-xs text-ink-200">Parent Portal</div>
				</Portal>
			</div>

			<BitsConfig defaultPortalTo="#config-child-target">
				<div class="grid gap-3">
					<ConfigProbe label="Nested config" />
					<Portal>
						<div class="panel animate-pop-in px-3 py-2 text-xs text-brand-400">Nested Portal</div>
					</Portal>
				</div>
			</BitsConfig>
		</div>
	</BitsConfig>

	<p class="muted text-center text-xs">
		The nested scope inherits <span class="font-mono">fr-FR</span>, but its Portal resolves to the nearer
		target override.
	</p>
</div>

BitsConfig supplies scoped defaults to Bits UI descendants. A direct component prop has highest priority, followed by the nearest BitsConfig, inherited ancestor configs, and finally the built-in default. This lets one nested scope override defaultPortalTo while retaining an ancestor's defaultLocale.

defaultPortalTo accepts an Element or selector string; without a configured value, portals use document.body. defaultLocale falls back to en. Provider defaults affect only components inside the provider's subtree.