Update from support feedback: clarify custom components are client-rendered

customize/react-components.mdx

@@ -216,8 +216,9 @@ import { ColorGenerator } from "/snippets/color-generator.jsx"
 
 ## Considerations
 
-- **SEO**: Search engines may not fully index client-rendered dynamic content.
-- **Initial load**: Visitors may see a flash before components render.
+- **Client-side rendering only**: Custom components render in the browser after the page loads, so they aren't in the server-rendered HTML. This applies to components you define with `export` in an MDX file and components you import by name from a snippet, such as `import { ColorGenerator } from "/snippets/color-generator.jsx"`. MDX snippets that you import as content, such as `import MySnippet from "/snippets/my-snippet.mdx"`, render on the server.
+- **SEO**: Because custom components are not in the initial HTML, search engines may not fully index their content.
+- **Initial load**: Visitors may see a flash or layout shift while custom components render. For content that must appear in the initial HTML or must not shift on load, use [built-in components](/components) such as [cards](/components/cards) and [columns](/components/columns) instead. Most built-in components render on the server.
 - **Accessibility**: Ensure screen readers announce dynamic content changes.
 - **Optimize dependency arrays**: Only include necessary dependencies in `useEffect`.
 - **Memoize expensive operations**: Use `useMemo` or `useCallback` where appropriate.

docs.json

@@ -508,7 +508,8 @@
                   "help-center/agent-opens-pull-requests-against-deploy-branch",
                   "help-center/publish-button-disabled-invalid-mdx",
                   "help-center/docs-json-href-must-be-a-valid-url",
-                  "help-center/endpoint-frontmatter-must-be-a-single-string"
+                  "help-center/endpoint-frontmatter-must-be-a-single-string",
+                  "help-center/custom-components-flash-or-missing-from-page-source"
                 ]
               }
             ]

help-center/custom-components-flash-or-missing-from-page-source.mdx

@@ -0,0 +1,29 @@
+---
+title: "Custom components flash or are missing from page source"
+description: "Custom React components in Mintlify render in the browser after the page loads, so they are not in the initial HTML. Use built-in components for content that must render on the server."
+keywords: ["custom component flash", "component pops in", "layout shift", "missing from page source", "view source", "server-side rendering", "SSR", "hydration", "snippets jsx", "React component not in HTML"]
+---
+
+If a React component that you wrote yourself appears a moment after the rest of a Mintlify page loads, or its content is missing when you view the page source, this is expected behavior. Mintlify renders custom components only in the browser.
+
+## Why custom components are not in the initial HTML
+
+Custom components run only in the browser. The server-rendered HTML leaves out components you define with `export` in an MDX file and components you import by name from a snippet, such as `import { MyComponent } from "/snippets/my-component.jsx"`. After the page loads, the browser renders those components in place.
+
+MDX snippets that you import as content, such as `import MySnippet from "/snippets/my-snippet.mdx"`, render on the server like the rest of the page.
+
+As a result:
+
+- The page source and the initial HTML do not include the component's content.
+- Visitors may see the component pop in or shift the layout after the rest of the page appears.
+- Search engines may not fully index the component's content.
+
+## Use built-in components for content that must render on the server
+
+Most [built-in components](/components), including the ones below, render on the server and appear in the initial HTML. If you use a custom component for layout or static content, replace it with a built-in component or an [MDX snippet](/create/reusable-snippets). For example:
+
+- Use [cards](/components/cards) and [columns](/components/columns) for grids of links or features.
+- Use [tabs](/components/tabs), [accordions](/components/accordions), and [steps](/components/steps) to organize content.
+- Use [callouts](/components/callouts) to highlight information.
+
+Keep custom components for interactive elements that need state or browser APIs. See [React components](/customize/react-components) for how to build them and other considerations.