> ## Documentation Index > Fetch the complete documentation index at: https://www.beeq.design/llms.txt > Use this file to discover all available pages before exploring further. # Shadows > BEEQ shadows define elevation, layering, and separation for surfaces that need to appear above the page. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return

{}

{} {children &&

{children}

}

; }; Shadows help users understand which surfaces sit above others. In BEEQ, shadows are used for elevation, temporary layers, overlays, and subtle separation when a border alone would feel too flat. Use shadows with intention. A stronger shadow should usually mean a stronger layer relationship, not a stronger state by itself. *** ## What BEEQ provides BEEQ provides a four-step box-shadow scale. The values are exposed as CSS custom properties and mapped into the BEEQ Tailwind preset when the preset is installed. Components that need elevation expose component-level shadow variables. Prefer those component variables when the shadow belongs to a BEEQ component, and use global shadow tokens for custom surfaces. | BEEQ provides | Use it for | | ------------------------ | --------------------------------------------------------------------------------------------------------- | | Box shadow variables | Custom surfaces, elevated panels, and product-specific layers. | | Tailwind preset mappings | Utility classes such as `shadow-xs`, `shadow-s`, `shadow-m`, and `shadow-l` when the preset is installed. | | Component CSS variables | Scoped shadow customization for components such as panel, dialog, toast, tooltip, and notification. | *** ## Shadow scale The shadow scale moves from subtle interaction lift to pronounced floating surfaces. Use the smallest shadow that communicates the layer relationship. | Token | CSS variable | Tailwind key | Value | Common use | | ----- | --------------------- | ------------ | --------------------------------------- | ---------------------------------------------------------------- | | `xs` | `--bq-box-shadow--xs` | `shadow-xs` | `0 2px 0 rgba(0, 0, 0, 0.016)` | Subtle interactive lift on compact elements. | | `s` | `--bq-box-shadow--s` | `shadow-s` | `0 8px 24px rgba(0, 0, 0, 0.04)` | Cards and stable elevated surfaces. | | `m` | `--bq-box-shadow--m` | `shadow-m` | `0 10px 48px -16px rgba(0, 0, 0, 0.12)` | Panels, dropdowns, sticky bars, and raised containers. | | `l` | `--bq-box-shadow--l` | `shadow-l` | `0 20px 58px -16px rgba(0, 0, 0, 0.16)` | Dialogs, toasts, notifications, and floating attention surfaces. | body { padding: var(--bq-spacing-m); } .shadow-scale { display: grid; grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-scale__tile { display: grid; align-content: space-between; gap: var(--bq-spacing-s); aspect-ratio: 1; padding: var(--bq-spacing-m); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--m); background: var(--bq-background--secondary); } .shadow-scale__tile--xs { box-shadow: var(--bq-box-shadow--xs); } .shadow-scale__tile--s { box-shadow: var(--bq-box-shadow--s); } .shadow-scale__tile--m { box-shadow: var(--bq-box-shadow--m); } .shadow-scale__tile--l { box-shadow: var(--bq-box-shadow--l); } .shadow-scale__value { color: var(--bq-text--secondary); font-size: var(--bq-font-size--s); }

xs Subtle interaction lift

s Stable surface elevation

m Panel or dropdown layer

l Floating attention layer

`} > ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .shadow-scale { display: grid; grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-scale__tile { padding: var(--bq-spacing-m); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--m); background: var(--bq-background--secondary); } .shadow-scale__tile--xs { box-shadow: var(--bq-box-shadow--xs); } .shadow-scale__tile--s { box-shadow: var(--bq-box-shadow--s); } .shadow-scale__tile--m { box-shadow: var(--bq-box-shadow--m); } .shadow-scale__tile--l { box-shadow: var(--bq-box-shadow--l); } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

xs Subtle interaction lift

s Stable surface elevation

m Panel or dropdown layer

l Floating attention layer

``` *** ## Elevation and layering Elevation should describe a surface relationship. A card can sit above the page. A panel can sit above the card. A dialog, toast, or notification can sit above the rest of the interface. Shadows should not be used as decoration. When every surface is elevated, users lose the visual hierarchy that elevation is meant to create. body { padding: var(--bq-spacing-m); } .shadow-layers { display: grid; grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-layer { display: grid; gap: var(--bq-spacing-xs); padding: var(--bq-spacing-l); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--m); background: var(--bq-background--secondary); } .shadow-layer--card { box-shadow: var(--bq-box-shadow--s); } .shadow-layer--panel { box-shadow: var(--bq-box-shadow--m); } .shadow-layer--floating { box-shadow: var(--bq-box-shadow--l); } .shadow-layer p { margin: 0; color: var(--bq-text--secondary); }

Card

Stable content lifted slightly from the page.

Panel

Temporary content that sits above a surface.

Floating UI

High-priority content that needs immediate attention.

`} > ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .shadow-layers { display: grid; grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-layer { padding: var(--bq-spacing-l); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--m); background: var(--bq-background--secondary); } .shadow-layer--card { box-shadow: var(--bq-box-shadow--s); } .shadow-layer--panel { box-shadow: var(--bq-box-shadow--m); } .shadow-layer--floating { box-shadow: var(--bq-box-shadow--l); } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Card

Stable content lifted slightly from the page.

Panel

Temporary content that sits above a surface.

Floating UI

High-priority content that needs immediate attention.

``` *** ## How shadows work in code Use CSS variables directly when you build custom UI. Use component CSS variables when the elevated surface belongs to a BEEQ component. If your project uses the BEEQ Tailwind preset, utilities such as `shadow-xs`, `shadow-s`, `shadow-m`, and `shadow-l` map to the same shadow variables. body { padding: var(--bq-spacing-m); } .shadow-code { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-code__surface { display: grid; gap: var(--bq-spacing-xs); padding: var(--bq-spacing-l); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--l); background: var(--bq-background--secondary); box-shadow: var(--bq-box-shadow--m); } .shadow-code__surface p { margin: 0; color: var(--bq-text--secondary); }

Custom floating surface

Use global shadow tokens when no BEEQ component owns the surface.

Product panel

Pair shadow with radius, stroke, and spacing tokens for a complete surface.

`} > ```css styles.css icon="css" theme={"theme":{"light":"one-light","dark":"night-owl"}} .shadow-code__surface { padding: var(--bq-spacing-l); border: var(--bq-stroke-s) solid var(--bq-stroke--primary); border-radius: var(--bq-radius--l); background: var(--bq-background--secondary); box-shadow: var(--bq-box-shadow--m); } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Custom floating surface

Use global shadow tokens when no BEEQ component owns the surface.

Product panel

Pair shadow with radius, stroke, and spacing tokens for a complete surface.

``` *** ## Component shadow customization Components that own elevated surfaces expose CSS variables for their shadow. Use those variables instead of targeting internal classes. | Component | CSS variable | Default shadow | Typical role | | ----------------- | ------------------------------- | ------------------------- | ------------------------------------------------------- | | `bq-panel` | `--bq-panel--box-shadow` | `var(--bq-box-shadow--m)` | Dropdowns, popovers, side panels, and temporary panels. | | `bq-dialog` | `--bq-dialog--box-shadow` | `var(--bq-box-shadow--l)` | Modal dialogs and blocking overlays. | | `bq-toast` | `--bq-toast--box-shadow` | `var(--bq-box-shadow--l)` | Time-based floating messages. | | `bq-notification` | `--bq-notification--box-shadow` | `var(--bq-box-shadow--l)` | Non-blocking notifications and alerts. | | `bq-tooltip` | `--bq-tooltip--box-shadow` | `var(--bq-box-shadow--m)` | Contextual helper text above the current surface. | body { padding: var(--bq-spacing-m); } .shadow-components { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-components__panel { --bq-panel--box-shadow: var(--bq-box-shadow--m); --bq-panel--border-style: solid; --bq-panel--border-width: var(--bq-stroke-s); --bq-panel--border-color: var(--bq-stroke--primary); --bq-panel--width: auto; --bq-panel--height: auto; } .shadow-components__panel::part(panel) { position: static; display: grid; gap: var(--bq-spacing-xs); inline-size: auto; } .shadow-components__toast { --bq-toast--box-shadow: var(--bq-box-shadow--l); display: block; } .shadow-components__notification { --bq-notification--box-shadow: var(--bq-box-shadow--l); --bq-notification--min-width: 0; }

Panel

Panel uses the medium shadow token for temporary layered content.

Notification Notifications use a stronger floating shadow.

Saved changes

`} > ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .shadow-components__panel { --bq-panel--box-shadow: var(--bq-box-shadow--m); --bq-panel--border-style: solid; --bq-panel--border-width: var(--bq-stroke-s); --bq-panel--border-color: var(--bq-stroke--primary); --bq-panel--width: auto; --bq-panel--height: auto; } .shadow-components__panel::part(panel) { position: static; display: grid; gap: var(--bq-spacing-xs); inline-size: auto; } .shadow-components__toast { --bq-toast--box-shadow: var(--bq-box-shadow--l); } .shadow-components__notification { --bq-notification--box-shadow: var(--bq-box-shadow--l); --bq-notification--min-width: 0; } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Panel

Panel uses the medium shadow token for temporary layered content.

Notification Notifications use a stronger floating shadow.

Saved changes

``` ### Components without shadow variables Some components do not expose a dedicated box-shadow variable. Use their documented shadow parts when a product-specific design needs elevation. Keep this restrained: a card or button shadow should support hierarchy or affordance, not make every action compete for attention. body { padding: var(--bq-spacing-m); } .shadow-parts { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-parts__card { --bq-card--borderColor: var(--bq-stroke--primary); --bq-card--borderWidth: var(--bq-stroke-s); } .shadow-parts__card::part(wrapper) { display: grid; gap: var(--bq-spacing-s); box-shadow: var(--bq-box-shadow--s); } .shadow-parts__button::part(button) { box-shadow: var(--bq-box-shadow--xs); }

Elevated card

Use the wrapper part when a card needs product-specific elevation.

Subtle lift

`} > ```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} .shadow-parts { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: var(--bq-spacing-m); } .shadow-parts__card { --bq-card--borderColor: var(--bq-stroke--primary); --bq-card--borderWidth: var(--bq-stroke-s); } .shadow-parts__card::part(wrapper) { display: grid; gap: var(--bq-spacing-s); box-shadow: var(--bq-box-shadow--s); } .shadow-parts__button::part(button) { box-shadow: var(--bq-box-shadow--xs); } ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Elevated card

Use the wrapper part when a card needs product-specific elevation.

Subtle lift

``` *** ## Choosing shadow Choose shadow based on how far a surface sits from the page, not how important the content feels. | Use | Recommended shadow | | -------------------------------------------------------- | ------------------------------------------------------ | | Subtle hover or interactive lift | `var(--bq-box-shadow--xs)` | | Card or stable elevated surface | `var(--bq-box-shadow--s)` | | Dropdown, panel, sticky bar, or raised container | `var(--bq-box-shadow--m)` | | Dialog, toast, notification, or floating attention layer | `var(--bq-box-shadow--l)` | | Dense data, table rows, and flat page sections | No shadow; use stroke, spacing, or background instead. | *** ## Usage guidelines Use `--bq-box-shadow--*` values instead of custom shadow values. The scale keeps elevation consistent across components and custom surfaces. Use stronger shadows only when the surface sits above another surface. Elevation should make the layer model easier to understand. Use `xs` or `s` for cards and low-emphasis surfaces. These shadows add separation without pulling attention away from content. Use `m` or `l` for panels, dropdowns, dialogs, toasts, notifications, and other temporary layers. Pair shadow changes with text, color, icon, stroke, or focus treatment when a state must be understood. A shadow works best when the surface also has enough padding, a clear edge, and a radius that matches its size. Multiple large shadows in the same region create visual noise and weaken the hierarchy. Use BEEQ tokens so shadows keep the intended weight in light and dark mode. *** ## Accessibility and constraints Shadows are visual cues. They can support hierarchy, but they cannot carry meaning alone. * Do not rely on shadow alone to indicate focus, selection, error, success, or disabled states. * Keep focus indicators visible when an elevated surface contains interactive elements. * Avoid shadows that make text or controls harder to read against nearby surfaces. * Use overlays, aria patterns, and focus management for blocking layers such as dialogs; shadow does not define modality. * Check zoomed and narrow layouts. Large shadows can make dense UI feel crowded or clipped. * Avoid clipping shadows with `overflow: hidden` unless the clipped edge is intentional. *** ## Resources Review the box-shadow variables used by BEEQ themes. See how BEEQ maps shadow tokens into Tailwind utilities. See the source that defines the BEEQ shadow values.