(() => { const values = ["system", "light", "dark"]; function savedPreference() { try { const stored = window.localStorage.getItem("isDarkMode"); return values.includes(stored) ? stored : "system"; } catch { return "system"; } } function itemPreference(item) { const text = item.textContent?.trim().toLowerCase() ?? ""; return values.find((value) => text.startsWith(value)); } function syncThemeSemantics() { const preference = savedPreference(); const trigger = document.querySelector('button[aria-label*="theme preference" i]'); const triggerLabel = `Theme: ${preference}. Change theme preference`; if (trigger?.getAttribute("aria-label") !== triggerLabel) { trigger?.setAttribute("aria-label", triggerLabel); } for (const item of document.querySelectorAll('[role="menuitem"]')) { const value = itemPreference(item); if (value === undefined) continue; const selected = value === preference; const current = selected ? "true" : null; if (item.getAttribute("aria-current") !== current) { if (current === null) item.removeAttribute("aria-current"); else item.setAttribute("aria-current", current); } } } function revealWithin(container, element) { if (!(container instanceof HTMLElement) || !(element instanceof HTMLElement)) return; const containerRect = container.getBoundingClientRect(); const elementRect = element.getBoundingClientRect(); if (elementRect.top < containerRect.top) { container.scrollTop -= containerRect.top - elementRect.top; } else if (elementRect.bottom > containerRect.bottom) { container.scrollTop += elementRect.bottom - containerRect.bottom; } } function syncNavigationSemantics() { const setAttribute = (element, name, value) => { if (element?.getAttribute(name) !== value) element?.setAttribute(name, value); }; const pageViewport = document.querySelector( '#sidebar [data-component-part="scroll-area-viewport"]', ); const activePage = document.querySelector( '#sidebar a[aria-current="page"], #sidebar a.text-primary, #sidebar [data-active="true"] a', ); revealWithin(pageViewport, activePage); const tocViewport = cachedTocViewport(); const activeHeading = document.querySelector( '#table-of-contents a[aria-current="location"], #table-of-contents [data-active-deepest="true"] a', ); revealWithin(tocViewport, activeHeading); const pagesTrigger = [...document.querySelectorAll("#navbar button")].find( (button) => button.querySelector(".sr-only")?.textContent?.trim() === "Navigation", ); const pagesDrawer = document.querySelector("#mobile-nav"); if (pagesTrigger) { setAttribute(pagesTrigger, "aria-label", "Pages"); setAttribute(pagesTrigger, "aria-controls", "mobile-nav"); setAttribute( pagesTrigger, "aria-expanded", pagesDrawer?.hasAttribute("data-open") ? "true" : "false", ); } if (pagesDrawer) { setAttribute(pagesDrawer, "aria-label", "Pages"); setAttribute(pagesDrawer, "role", "dialog"); setAttribute(pagesDrawer, "aria-modal", "true"); setAttribute( pagesDrawer.querySelector('button[aria-label="Close navigation"]'), "aria-label", "Close Pages", ); } const pagesOpen = Boolean(pagesDrawer?.hasAttribute("data-open")); if (pagesDrawer) setAttribute(pagesDrawer, "aria-hidden", pagesOpen ? "false" : "true"); document.documentElement.toggleAttribute("data-ag-pages-open", pagesOpen); syncPagesBackground(pagesDrawer, pagesOpen); if (!pagesWasOpen && pagesOpen) { window.requestAnimationFrame(() => pagesDrawer?.querySelector("button, a[href]")?.focus()); } if (pagesWasOpen && !pagesOpen) { window.requestAnimationFrame(() => ( document.querySelector('#navbar button[aria-label="Pages"]') ?? pagesTriggerForRestore )?.focus(), ); } pagesWasOpen = pagesOpen; const tocOpen = Boolean(document.querySelector("#ag-mobile-toc:not([hidden])")); if (onThisPageWasOpen && !tocOpen) { window.requestAnimationFrame(() => document.querySelector("#ag-mobile-toc-trigger")?.focus()); } onThisPageWasOpen = tocOpen; } let tocViewportCache; function cachedTocViewport() { if (tocViewportCache?.isConnected) return tocViewportCache; tocViewportCache = [...document.querySelectorAll("#table-of-contents *")].find( (element) => getComputedStyle(element).overflowY === "scroll", ); return tocViewportCache; } let onThisPageTrigger; let onThisPageDrawer; let onThisPageBackdrop; let pendingLocationHash = window.location.hash; let pagesWasOpen = false; let pagesTriggerForRestore; const pagesBackground = new Map(); const onThisPageBackground = new Map(); let onThisPageWasOpen = false; let searchDialogActive; let searchBackground; let searchTriggerForRestore; function syncPagesBackground(drawer, open) { if (open && drawer instanceof HTMLElement && pagesBackground.size === 0) { for (const element of document.querySelectorAll( "main, #sidebar, #table-of-contents, footer", )) { if ( !(element instanceof HTMLElement) || element.contains(drawer) || drawer.contains(element) ) { continue; } pagesBackground.set(element, { ariaHidden: element.getAttribute("aria-hidden"), inert: element.inert, }); element.inert = true; element.setAttribute("aria-hidden", "true"); } } else if (!open && pagesBackground.size > 0) { for (const [element, previous] of pagesBackground) { element.inert = previous.inert; if (previous.ariaHidden === null) element.removeAttribute("aria-hidden"); else element.setAttribute("aria-hidden", previous.ariaHidden); } pagesBackground.clear(); } } function containPagesFocus(event) { const drawer = document.querySelector("#mobile-nav[data-open]"); if (event.key !== "Tab" || !(drawer instanceof HTMLElement)) return; const focusable = focusableWithin(drawer); if (focusable.length === 0) { event.preventDefault(); drawer.focus(); return; } const first = focusable[0]; const last = focusable.at(-1); if (event.shiftKey && (document.activeElement === first || document.activeElement === drawer)) { event.preventDefault(); last?.focus(); } else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus(); } } function syncOnThisPageBackground(open) { if (open && onThisPageDrawer instanceof HTMLElement && onThisPageBackground.size === 0) { for (const element of document.querySelectorAll( "#navbar, main, #sidebar, #table-of-contents, footer", )) { if ( !(element instanceof HTMLElement) || element.contains(onThisPageDrawer) || onThisPageDrawer.contains(element) ) { continue; } onThisPageBackground.set(element, { ariaHidden: element.getAttribute("aria-hidden"), inert: element.inert, }); element.inert = true; element.setAttribute("aria-hidden", "true"); } } else if (!open && onThisPageBackground.size > 0) { for (const [element, previous] of onThisPageBackground) { element.inert = previous.inert; if (previous.ariaHidden === null) element.removeAttribute("aria-hidden"); else element.setAttribute("aria-hidden", previous.ariaHidden); } onThisPageBackground.clear(); } } function bodyChildContaining(element) { if (!(element instanceof HTMLElement)) return; let current = element; while (current.parentElement && current.parentElement !== document.body) { current = current.parentElement; } return current.parentElement === document.body ? current : undefined; } function visibleSearchDialog() { return [...document.querySelectorAll('[role="dialog"]')].find( (element) => element.id !== "ag-mobile-toc" && element.getAttribute("aria-label")?.startsWith("Search") && !element.hidden && getComputedStyle(element).display !== "none" && element.getBoundingClientRect().width > 0, ); } function focusableWithin(element) { return [ ...element.querySelectorAll("button, a[href], input, select, textarea, [tabindex]"), ].filter( (element) => !element.disabled && element.getAttribute("tabindex") !== "-1" && getComputedStyle(element).display !== "none" && element.getBoundingClientRect().width > 1 && element.getBoundingClientRect().height > 1, ); } function restoreSearchBackground(element) { const currentAppRoot = bodyChildContaining(document.querySelector("#navbar")) ?? element; currentAppRoot.inert = false; currentAppRoot.setAttribute("aria-hidden", "false"); } function syncSearchAccessibility() { const dialog = visibleSearchDialog(); if (!dialog) { if (!searchDialogActive) return; document.documentElement.removeAttribute("data-ag-search-open"); if (searchBackground) { restoreSearchBackground(searchBackground); } searchDialogActive = undefined; searchBackground = undefined; window.requestAnimationFrame(() => searchTriggerForRestore?.focus()); return; } dialog.setAttribute("aria-modal", "true"); dialog.setAttribute("data-ag-search-dialog", ""); dialog.tabIndex = -1; dialog.setAttribute("aria-label", "Search Developer Docs"); const preferredFocus = dialog.querySelector( 'input:not([aria-hidden="true"]):not([type="hidden"]), textarea, [contenteditable="true"]', ); if (searchDialogActive !== dialog) { searchDialogActive = dialog; document.documentElement.setAttribute("data-ag-search-open", ""); const appRoot = bodyChildContaining(document.querySelector("#navbar")); const dialogRoot = bodyChildContaining(dialog); if (appRoot && appRoot !== dialogRoot) { searchBackground = appRoot; appRoot.inert = true; appRoot.setAttribute("aria-hidden", "true"); } (preferredFocus ?? dialog).focus({ preventScroll: true }); } else if (!dialog.contains(document.activeElement)) { (preferredFocus ?? dialog).focus({ preventScroll: true }); } } function syncCodeOverflowAccessibility() { for (const viewport of document.querySelectorAll( '.code-block [data-component-part="scroll-area-viewport"]', )) { if (!(viewport instanceof HTMLElement)) continue; const overflows = viewport.scrollWidth > viewport.clientWidth + 1; if (overflows) { viewport.tabIndex = 0; viewport.setAttribute("role", "region"); viewport.setAttribute("aria-label", "Scrollable code example"); viewport.setAttribute("data-ag-code-scroll", ""); } else if (viewport.hasAttribute("data-ag-code-scroll")) { viewport.removeAttribute("tabindex"); viewport.removeAttribute("role"); viewport.removeAttribute("aria-label"); viewport.removeAttribute("data-ag-code-scroll"); } } } function syncCodeGroupAccessibility() { for (const tablist of document.querySelectorAll( '[role="tablist"][aria-label="Code examples"]', )) { if (!(tablist instanceof HTMLElement)) continue; const tabs = [...tablist.querySelectorAll('[role="tab"]')].filter( (tab) => tab instanceof HTMLButtonElement, ); const selected = tabs.find((tab) => tab.getAttribute("aria-selected") === "true") ?? tabs[0]; tabs.forEach((tab) => { tab.tabIndex = tab === selected ? 0 : -1; }); if (tablist.hasAttribute("data-ag-tabs-ready")) continue; tablist.setAttribute("data-ag-tabs-ready", ""); tablist.addEventListener("keydown", (event) => { const currentTabs = [...tablist.querySelectorAll('[role="tab"]')].filter( (tab) => tab instanceof HTMLButtonElement, ); const currentIndex = currentTabs.indexOf(event.target); if (currentIndex < 0) return; let nextIndex; if (event.key === "ArrowRight") nextIndex = (currentIndex + 1) % currentTabs.length; else if (event.key === "ArrowLeft") nextIndex = (currentIndex - 1 + currentTabs.length) % currentTabs.length; else if (event.key === "Home") nextIndex = 0; else if (event.key === "End") nextIndex = currentTabs.length - 1; else return; event.preventDefault(); const next = currentTabs[nextIndex]; currentTabs.forEach((tab) => { tab.tabIndex = tab === next ? 0 : -1; }); next?.focus(); next?.scrollIntoView({ block: "nearest", inline: "nearest" }); next?.click(); }); } } let copyStatusSequence = 0; function syncCopyControls() { for (const button of document.querySelectorAll('[data-testid="copy-code-button"]')) { if (!(button instanceof HTMLButtonElement)) continue; const status = button.parentElement?.querySelector('[role="status"]'); const copied = status?.textContent?.trim() === "Copied"; button.setAttribute("aria-label", copied ? "Copied" : "Copy code"); button.setAttribute("title", copied ? "Copied" : "Copy code"); button.toggleAttribute("data-ag-copied", copied); if (status instanceof HTMLElement) { status.id ||= `ag-copy-status-${++copyStatusSequence}`; button.setAttribute("aria-describedby", status.id); } } } function syncCodeLanguageLabels() { const names = { json: "JSON", shellscript: "Shell", text: "Text", typescript: "TypeScript", }; for (const root of document.querySelectorAll('[data-component-part="code-block-root"]')) { if (!(root instanceof HTMLElement) || root.closest(".code-group")) continue; if (root.querySelector(":scope > .ag-code-language")) continue; const language = root.querySelector("pre[language]")?.getAttribute("language"); if (!language) continue; const label = document.createElement("span"); label.className = "ag-code-language"; label.setAttribute("aria-hidden", "true"); label.dataset.label = names[language] ?? language; root.prepend(label); root.setAttribute("data-ag-has-language", ""); } } function syncTableAccessibility() { for (const viewport of document.querySelectorAll( '[data-table-wrapper="true"] [data-component-part="scroll-area-viewport"]', )) { if (!(viewport instanceof HTMLElement)) continue; const overflows = viewport.scrollWidth > viewport.clientWidth + 1; if (overflows) { viewport.tabIndex = 0; viewport.setAttribute("role", "region"); viewport.setAttribute("aria-label", "Scrollable table"); viewport.setAttribute("data-ag-table-scroll", ""); } else { viewport.removeAttribute("tabindex"); viewport.removeAttribute("role"); if (viewport.getAttribute("aria-label") === "Scrollable table") { viewport.removeAttribute("aria-label"); } viewport.removeAttribute("data-ag-table-scroll"); } } } function containSearchFocus(event) { const dialog = searchDialogActive; if (event.key !== "Tab" || !dialog) return; const focusable = focusableWithin(dialog); if (focusable.length === 0) { event.preventDefault(); dialog.focus(); return; } const first = focusable[0]; const last = focusable.at(-1); if (event.shiftKey && (document.activeElement === first || document.activeElement === dialog)) { event.preventDefault(); last?.focus(); } else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus(); } } function closeOnThisPage({ restoreFocus = false } = {}) { if (!onThisPageDrawer || !onThisPageBackdrop || !onThisPageTrigger) return; onThisPageDrawer.hidden = true; onThisPageDrawer.setAttribute("aria-hidden", "true"); onThisPageTrigger.setAttribute("aria-expanded", "false"); onThisPageBackdrop.hidden = true; document.documentElement.removeAttribute("data-ag-toc-open"); syncOnThisPageBackground(false); if (restoreFocus) { window.setTimeout(() => document.querySelector("#ag-mobile-toc-trigger")?.focus(), 100); } } function locationHashScrollTop({ currentScrollY, navbarBottom, targetTop }) { return Math.max(0, currentScrollY + targetTop - navbarBottom - 40); } function syncLocationHash() { if (!pendingLocationHash) return; const target = document.getElementById(pendingLocationHash.slice(1)); if (!target) return; pendingLocationHash = ""; const navbarBottom = document.querySelector("#navbar")?.getBoundingClientRect().bottom ?? 0; const targetTop = target.getBoundingClientRect().top; window.scrollTo({ behavior: "auto", top: locationHashScrollTop({ currentScrollY: window.scrollY, navbarBottom, targetTop, }), }); } function buildOnThisPage() { if (!onThisPageDrawer) return; const source = document.querySelector("#table-of-contents-content"); const target = onThisPageDrawer.querySelector(".ag-mobile-toc-list"); if (!source || !target) return; target.replaceChildren(...[...source.children].map((item) => item.cloneNode(true))); target.querySelectorAll("a").forEach((link) => { link.addEventListener("click", () => closeOnThisPage()); }); } function openOnThisPage() { if (!onThisPageDrawer || !onThisPageBackdrop || !onThisPageTrigger) return; buildOnThisPage(); onThisPageDrawer.hidden = false; onThisPageDrawer.removeAttribute("aria-hidden"); onThisPageTrigger.setAttribute("aria-expanded", "true"); onThisPageBackdrop.hidden = false; document.documentElement.setAttribute("data-ag-toc-open", ""); syncOnThisPageBackground(true); onThisPageDrawer.querySelector("button, a")?.focus(); } function containOnThisPageFocus(event) { if (event.key !== "Tab" || onThisPageDrawer?.hidden) return; const focusable = [...onThisPageDrawer.querySelectorAll("button, a[href]")].filter( (element) => !element.hidden, ); const first = focusable[0]; const last = focusable.at(-1); if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last?.focus(); } else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus(); } } function ensureMobileOnThisPage() { const pagesTrigger = document.querySelector('#navbar button[aria-label="Pages"]'); if (!pagesTrigger || document.querySelector("#ag-mobile-toc-trigger")) return; onThisPageTrigger = document.createElement("button"); onThisPageTrigger.id = "ag-mobile-toc-trigger"; onThisPageTrigger.type = "button"; onThisPageTrigger.textContent = "On this page"; onThisPageTrigger.setAttribute("aria-controls", "ag-mobile-toc"); onThisPageTrigger.setAttribute("aria-expanded", "false"); pagesTrigger.insertAdjacentElement("afterend", onThisPageTrigger); onThisPageBackdrop = document.createElement("button"); onThisPageBackdrop.id = "ag-mobile-toc-backdrop"; onThisPageBackdrop.type = "button"; onThisPageBackdrop.hidden = true; onThisPageBackdrop.setAttribute("aria-label", "Close On this page"); onThisPageDrawer = document.createElement("aside"); onThisPageDrawer.id = "ag-mobile-toc"; onThisPageDrawer.hidden = true; onThisPageDrawer.setAttribute("role", "dialog"); onThisPageDrawer.setAttribute("aria-modal", "true"); onThisPageDrawer.setAttribute("aria-label", "On this page"); onThisPageDrawer.setAttribute("aria-hidden", "true"); onThisPageDrawer.innerHTML = `

On this page

`; document.body.append(onThisPageBackdrop, onThisPageDrawer); onThisPageTrigger.addEventListener("click", openOnThisPage); onThisPageBackdrop.addEventListener("click", () => closeOnThisPage({ restoreFocus: true })); onThisPageDrawer .querySelector("header button") ?.addEventListener("click", () => closeOnThisPage({ restoreFocus: true })); onThisPageDrawer.addEventListener("keydown", containOnThisPageFocus); } let scheduled = false; let scheduledScrollOnly = true; function scheduleSync({ scrollOnly = false } = {}) { if (!scrollOnly) scheduledScrollOnly = false; if (scheduled) return; scheduled = true; window.requestAnimationFrame(() => { scheduled = false; const scrollTick = scheduledScrollOnly; scheduledScrollOnly = true; syncNavigationSemantics(); syncLocationHash(); // Scrolling only moves the active heading. The passes below either read layout for every // code block and table or rewrite ARIA state, and neither changes on a scroll tick. if (scrollTick) return; syncThemeSemantics(); ensureMobileOnThisPage(); syncSearchAccessibility(); syncCodeOverflowAccessibility(); syncCodeGroupAccessibility(); syncCopyControls(); syncCodeLanguageLabels(); syncTableAccessibility(); }); } const observer = new MutationObserver(() => scheduleSync()); observer.observe(document.documentElement, { attributeFilter: ["class"], attributes: true, childList: true, subtree: true, }); document.addEventListener( "click", (event) => { const trigger = event.target.closest?.('#navbar button[aria-label="Pages"]'); if (trigger) pagesTriggerForRestore = trigger; const searchTrigger = event.target.closest?.('button[aria-label="Open search"]'); if (searchTrigger) searchTriggerForRestore = searchTrigger; scheduleSync(); }, true, ); document.addEventListener("keydown", (event) => { containPagesFocus(event); containSearchFocus(event); if (event.key === "Escape" && onThisPageDrawer && !onThisPageDrawer.hidden) { closeOnThisPage({ restoreFocus: true }); } if (event.key === "Escape" && searchDialogActive) window.setTimeout(scheduleSync); }); window.addEventListener("resize", scheduleSync); window.addEventListener("hashchange", () => { pendingLocationHash = window.location.hash; scheduleSync(); }); window.addEventListener("popstate", () => { pendingLocationHash = window.location.hash; scheduleSync(); }); window.addEventListener("pageshow", () => { pendingLocationHash = window.location.hash; scheduleSync(); }); window.addEventListener("scroll", () => scheduleSync({ scrollOnly: true }), { passive: true }); window.addEventListener("storage", scheduleSync); scheduleSync(); })();

​Common topics

Getting started

Authentication

​Still need help?

Common topics

Still need help?