From 4c4e7353661f7e440e9a82f7dcd85de8d2db6749 Mon Sep 17 00:00:00 2001 From: Sarah Gerrard Date: Thu, 9 Apr 2026 11:05:23 -0700 Subject: [PATCH 1/7] router, preload, useSubmission, useSubmissions --- .../reference/components/router.mdx | 128 ++++++++++++++++-- .../reference/data-apis/use-submission.mdx | 41 ++++-- .../reference/data-apis/use-submissions.mdx | 39 ++++-- .../reference/preload-functions/preload.mdx | 33 ++--- 4 files changed, 192 insertions(+), 49 deletions(-) diff --git a/src/routes/solid-router/reference/components/router.mdx b/src/routes/solid-router/reference/components/router.mdx index 7400ea5a6..d86caa33f 100644 --- a/src/routes/solid-router/reference/components/router.mdx +++ b/src/routes/solid-router/reference/components/router.mdx @@ -16,8 +16,122 @@ description: >- context and configuration for all child routes and navigation. --- -The `Router` component is a top level component that manages the routing of your application. -There is an optional `root` prop that can be used to wrap the entire application in a layout component, which will not be updated when the page changes. +`Router` is the top-level component that manages routing for the application. +It provides the routing context used by route matching, navigation, link interception, and route preloading. + +## Import + +```tsx +import { Router } from "@solidjs/router"; +``` + +## Type + +```tsx +type RouterProps = BaseRouterProps & { + url?: string; + actionBase?: string; + explicitLinks?: boolean; + preload?: boolean; +}; + +type BaseRouterProps = { + base?: string; + root?: Component; + rootPreload?: RoutePreloadFunc; + singleFlight?: boolean; + children?: JSX.Element | RouteDefinition | RouteDefinition[]; + transformUrl?: (url: string) => string; + /* @deprecated use rootPreload */ + rootLoad?: RoutePreloadFunc; +}; +``` + +## Props + +### `base` + +- **Type:** `string` +- **Optional:** Yes + +Base URL used for route matching and path resolution. + +### `root` + +- **Type:** `Component` +- **Optional:** Yes + +Layout component that wraps the matched route and stays mounted while the matched route subtree changes. It receives `params`, `location`, `data`, and `children` through `RouteSectionProps`. + +### `rootPreload` + +- **Type:** `RoutePreloadFunc` +- **Optional:** Yes + +Preload function for the root route context. Its return value is passed to the `root` component through the `data` field in `RouteSectionProps`. + +### `singleFlight` + +- **Type:** `boolean` +- **Default:** `true` +- **Optional:** Yes + +Enables or disables single-flight handling for actions. This only affects actions that support `withOptions`. + +### `children` + +- **Type:** `JSX.Element | RouteDefinition | RouteDefinition[]` +- **Optional:** Yes + +Route definitions. + +### `transformUrl` + +- **Type:** `(url: string) => string` +- **Optional:** Yes + +Transforms the pathname before route matching and anchor preloading. + +### `rootLoad` + +- **Type:** `RoutePreloadFunc` +- **Optional:** Yes + +Deprecated alias for `rootPreload`. + +### `actionBase` + +- **Type:** `string` +- **Default:** `"/_server"` +- **Optional:** Yes + +Base path for intercepted action form submissions. Only `POST` forms whose normalized action path starts with this base are intercepted. + +### `explicitLinks` + +- **Type:** `boolean` +- **Default:** `false` +- **Optional:** Yes + +When `true`, only anchors marked with the `link` attribute are intercepted. When `false`, matching same-origin anchors are intercepted automatically. + +### `preload` + +- **Type:** `boolean` +- **Default:** `true` +- **Optional:** Yes + +Enables or disables link and focus-based route preloading. When enabled, preloading is triggered from mouse move, focus, and touchstart on intercepted anchors. + +## Behavior + +- On the server, `Router` delegates to `StaticRouter`, which is the only path where `url` is used. +- On the client, `Router` reads from and writes to the browser history using the current `pathname`, `search`, and `hash`. +- When navigation writes history state, `Router` preserves the internal history depth metadata used by blocked back and forward navigation. +- `rootLoad` is still supported and is used as a fallback when `rootPreload` is not provided. +- Link interception, route preloading, and action form interception are handled through delegated document-level event listeners. + +## Examples ```tsx import { render } from "solid-js/web"; @@ -35,13 +149,3 @@ render( document.getElementById("root") ); ``` - -| prop | type | description | -| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| children | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions | -| root | Component | Top level layout component | -| base | string | Base url to use for matching routes | -| actionBase | string | Root url for server actions, default: `/_server` | -| preload | boolean | Enables/disables preloads globally, default: `true` | -| explicitLinks | boolean | Disables all anchors being intercepted and instead requires ``. default: `false`. (To disable interception for a specific link, set `target` to any value, e.g. ``.) | -| url | string | The initial route to render | diff --git a/src/routes/solid-router/reference/data-apis/use-submission.mdx b/src/routes/solid-router/reference/data-apis/use-submission.mdx index ff9bfec65..26242a80f 100644 --- a/src/routes/solid-router/reference/data-apis/use-submission.mdx +++ b/src/routes/solid-router/reference/data-apis/use-submission.mdx @@ -16,7 +16,7 @@ description: >- optimistic updates, and errors for single forms. --- -The `useSubmission` primitive returns the state of the _most recent_ submission for a given [action](/solid-router/concepts/actions). +`useSubmission` returns the most recent tracked submission for an [action](/solid-router/concepts/actions). ## Import @@ -47,10 +47,7 @@ The action to track. - **Type:** `(input: V) => boolean` - **Required:** No -A function that filters submissions. -It is executed for each submission in the order of creation. -It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise. -The first submission that passes the filter is returned by `useSubmission`. +A function that receives the action input and returns `true` for matching submissions. ## Return value @@ -58,27 +55,49 @@ The first submission that passes the filter is returned by `useSubmission`. ### `input` -A reactive value representing the input data of the action. +- **Type:** `T | undefined` +- **Defined when:** A matching submission exists. + +Reactive input data for the submission. ### `result` -A reactive value representing the successful return value of the action. +- **Type:** `NarrowResponse | undefined` +- **Defined when:** The submission completes successfully. + +Reactive successful return value for the submission. ### `error` -A reactive value representing any error thrown by the action. +- **Type:** `any` +- **Defined when:** The submission throws or rejects. + +Reactive error value for the submission. ### `pending` -A reactive boolean indicating if the action is currently running. +- **Type:** `boolean | undefined` +- **Defined when:** A matching submission exists. + +Whether the submission is still running. ### `clear` -A function to clear the submission's state. +- **Type:** `() => void` + +Clears the submission state. ### `retry` -A function to re-execute the submission with the same input. +- **Type:** `() => void` + +Re-executes the submission with the same input. + +## Behavior + +- `useSubmission` reads from the router's tracked submissions for the given action. +- If a `filter` is provided, it returns the most recent submission whose input matches the filter. +- If there is no matching submission, it returns a stub with `undefined` data fields and no-op `clear` and `retry` methods. ## Examples diff --git a/src/routes/solid-router/reference/data-apis/use-submissions.mdx b/src/routes/solid-router/reference/data-apis/use-submissions.mdx index 96cf940ed..18f45935b 100644 --- a/src/routes/solid-router/reference/data-apis/use-submissions.mdx +++ b/src/routes/solid-router/reference/data-apis/use-submissions.mdx @@ -16,7 +16,7 @@ description: >- history, handle errors, and show optimistic updates. --- -The `useSubmissions` primitive returns the state of all submissions for a given [action](/solid-router/concepts/actions). +`useSubmissions` returns the state of all tracked submissions for an [action](/solid-router/concepts/actions). ## Import @@ -49,9 +49,8 @@ The action to track. - **Type:** `(input: V) => boolean` - **Required:** No -A function that filters submissions. -It is executed for each submission in the order of creation. -It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise. +A function that receives the action input and returns `true` for matching submissions. +Only matching submissions are included in the returned array. ## Return value @@ -60,27 +59,47 @@ Each submission object has the following properties: ### `input` -The reactive input data of the action. +- **Type:** `T` + +Reactive input data for the submission. ### `result` -A reactive value representing the successful return value of the action. +- **Type:** `NarrowResponse | undefined` +- **Defined when:** The submission completes successfully. + +Reactive successful return value for the submission. ### `error` -A reactive value for any error thrown by the action. +- **Type:** `any` +- **Defined when:** The submission throws or rejects. + +Reactive error value for the submission. ### `pending` -A reactive boolean indicating if the action is currently running. +- **Type:** `boolean` + +Whether the submission is still running. ### `clear` -A function to clear the submission's state. +- **Type:** `() => void` + +Clears the submission state. ### `retry` -A function to re-execute the submission with the same input. +- **Type:** `() => void` + +Re-executes the submission with the same input. + +## Behavior + +- `useSubmissions` returns a reactive array backed by the router's tracked submissions for the given action. +- If a `filter` is provided, only submissions whose input matches the filter are included. +- The returned array also exposes a `pending` property that is `true` when any included submission does not yet have a result. ## Examples diff --git a/src/routes/solid-router/reference/preload-functions/preload.mdx b/src/routes/solid-router/reference/preload-functions/preload.mdx index aea659caa..5f3986637 100644 --- a/src/routes/solid-router/reference/preload-functions/preload.mdx +++ b/src/routes/solid-router/reference/preload-functions/preload.mdx @@ -16,14 +16,7 @@ description: >- prefetching for instant page transitions. --- -The `preload` function is a property on a route definition that initiates data fetching before a user navigates to the route. - -`preload` runs in two separate phases: - -- **Preload phase:** - Triggered by user intent (e.g., hovering over a link), the function is called to initiate data fetching. -- **Rendering phase:** - Triggered by actual navigation, the function is called a second time to provide the fetched data to the component. +`preload` is a route-definition property that runs during route preloading and rendering. ## Import @@ -65,19 +58,27 @@ It corresponds to the value returned by the [`useLocation` primitive](/solid-rou A string indicating the context in which the function is called. -- `"preload"`: - The function is running to initiate data fetching. -- `"navigate"`: - The function is running during navigation to the route. -- `"initial"`: - The function is running for the first route on page load. +| Value | Meaning | +| ---------- | ------------------------------------------------------------------ | +| `preload` | Preloading route code or data. | +| `navigate` | Client navigation to the route. | +| `native` | Native history navigation, such as back or forward. | +| `initial` | The first render for the current request or page load. | ## Return value The value returned by `preload` is passed to the route's component as the `data` prop. -- In the **preload phase** (`intent: "preload"`), the return value is **ignored**. -- In the **rendering phase** (`intent: "navigate"` or `"initial"`), the return value is **captured** and provided to the component. +| Intent | Return value behavior | +| ----------------------------------- | --------------------------------------------- | +| `preload` | Ignored. | +| `initial`, `navigate`, or `native` | Captured and passed to the component as `data`. | + +## Behavior + +- During route preloading, the router calls `preload` for each matched route. +- `load` is a deprecated alias for `preload` on route definitions. +- Route component preloads run before the route's `preload` function when the component exposes a `.preload()` method. ## Examples From 008968a6c0f4b5396770248b363717a0f599a3fb Mon Sep 17 00:00:00 2001 From: Sarah Gerrard Date: Thu, 9 Apr 2026 12:02:08 -0700 Subject: [PATCH 2/7] add templates and some solid-meta ref updates --- src/routes/solid-meta/reference/meta/base.mdx | 63 ++++- src/routes/solid-meta/reference/meta/link.mdx | 242 +++++++++++++++--- .../reference/meta/metaprovider.mdx | 84 +++++- templates/reference-component-template.mdx | 66 +++++ templates/reference-function-template.mdx | 72 ++++++ .../reference-object-return-template.mdx | 76 ++++++ templates/reference-property-template.mdx | 63 +++++ 7 files changed, 610 insertions(+), 56 deletions(-) create mode 100644 templates/reference-component-template.mdx create mode 100644 templates/reference-function-template.mdx create mode 100644 templates/reference-object-return-template.mdx create mode 100644 templates/reference-property-template.mdx diff --git a/src/routes/solid-meta/reference/meta/base.mdx b/src/routes/solid-meta/reference/meta/base.mdx index 91a1607df..65331c629 100644 --- a/src/routes/solid-meta/reference/meta/base.mdx +++ b/src/routes/solid-meta/reference/meta/base.mdx @@ -2,8 +2,7 @@ title: Base order: 5 use_cases: >- - setting base url, relative urls, external resources, multi-page apps, cdn - assets + base URL, relative URL resolution, document base, target defaults tags: - base - url @@ -12,31 +11,69 @@ tags: - routing version: "1.0" description: >- - Set the base URL for all relative URLs in your Solid app with the Base - component. Essential for apps with complex routing or external resources. + Render a `base` element in the current `MetaProvider`. --- -`Base` is a component that specifies the base URL for all relative URLs in the document. -This provides a way to define the [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) element of your document's `head`. +`Base` renders a [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/base) element in the current [`MetaProvider`](/solid-meta/reference/meta/metaprovider) to set the document base URL or default browsing context for relative URLs and navigation targets. -```tsx twoslash +## Import + +```tsx import { Base } from "@solidjs/meta"; +``` + +## Type -; +```tsx +function Base(props: JSX.BaseHTMLAttributes): null; ``` -## Usage +## Props + +### `href` + +- **Type:** `string` +- **Optional:** Yes + +Document base URL. + +For URL resolution details, see MDN's [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base#href) reference. + +### `target` + +- **Type:** `string` +- **Default:** `"_self"` +- **Optional:** Yes -### Adding `base` tag +Default browsing context for relative links and form submissions. -```tsx twoslash +Common values include `"_self"`, `"_blank"`, `"_parent"`, and `"_top"`. + +For browsing-context keywords and target behavior, see MDN's [`target`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base#target) reference. + +## Behavior + +- `Base` requires a surrounding [`MetaProvider`](/solid-meta/reference/meta/metaprovider). +- `Base` is a void element. During SSR, `@solidjs/meta` renders it as a self-closing tag. +- `@solidjs/meta` does not deduplicate `Base` tags. If multiple `Base` components are rendered, it appends multiple `base` elements to `head`. + +## Examples + +### Basic usage + +```tsx import { MetaProvider, Base } from "@solidjs/meta"; -export default function Root() { +function App() { return ( - + ); } ``` + +## Related + +- [``](/solid-meta/reference/meta/metaprovider) +- [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/link.mdx b/src/routes/solid-meta/reference/meta/link.mdx index 3220ebf12..f25c5531e 100644 --- a/src/routes/solid-meta/reference/meta/link.mdx +++ b/src/routes/solid-meta/reference/meta/link.mdx @@ -1,7 +1,7 @@ --- title: Link order: 2 -use_cases: "adding favicon, stylesheets, external resources, preloading assets, web fonts" +use_cases: "favicons, stylesheets, preload hints, canonical URLs, head links" tags: - link - favicon @@ -11,61 +11,233 @@ tags: - resources version: "1.0" description: >- - Add external resources like stylesheets and favicons to your Solid app. Learn - to use the Link component for optimal resource loading and icons. + Render a `link` element in the current `MetaProvider`. --- -The Link component establishes a connection between the page and an external resource. -Commonly, this is used for linking stylesheets and other associations. +`Link` renders a [`link`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element in the current [`MetaProvider`](/solid-meta/reference/meta/metaprovider) to register an external resource or relationship in the document head. -This component renders a [`link`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element within the document's ``. +## Import -```tsx twoslash +```tsx import { Link } from "@solidjs/meta"; -; ``` -## Usage +## Type -### Adding a favicon +```tsx +function Link(props: JSX.LinkHTMLAttributes): null; +``` -To add a favicon in an app, `` can be used to point to the asset: +## Props -```tsx twoslash -import { MetaProvider, Link } from "@solidjs/meta"; +### `href` -export default function Root() { - return ( - - - - ); -} -``` +- **Type:** `string` +- **Optional:** Yes -### Using an emoji as a favicon +Resource URL. -To use an emoji as a favicon, first create a function that returns a data URI containing an SVG image: +### `rel` -```jsx -const emojiSvg = (emoji) => { - return ( - `data:image/svg+xml;utf8,` + - `${emoji}` - ); -}; -``` +- **Type:** `string` +- **Optional:** Yes + +Relationship between the current document and the linked resource. +Value is a space-separated set of link-relation keywords. + +Common values: + +| Value | Meaning | +| --- | --- | +| `alternate` | Identifies an alternate representation of the current document. | +| `canonical` | Identifies the preferred URL for the current document. | +| `icon` | Identifies an icon for the current document. | +| `manifest` | Links a web app manifest. | +| `modulepreload` | Requests early loading of a JavaScript module graph. | +| `preconnect` | Requests an early connection to another origin. | +| `dns-prefetch` | Requests early DNS resolution for another origin. | +| `prefetch` | Hints that the resource may be needed for a future navigation. | +| `preload` | Hints that the resource is likely needed for the current navigation. | +| `stylesheet` | Identifies an external stylesheet. | + +For the full set of relation keywords, see MDN's [`rel`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#rel) reference. + +### `as` + +- **Type:** `string` +- **Optional:** Yes + +Resource destination type. + +Common values include `"audio"`, `"document"`, `"fetch"`, `"font"`, `"image"`, `"script"`, `"style"`, `"track"`, `"video"`, and `"worker"`. + +For the full set of destination values, see MDN's [`as`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#as) reference. + +### `blocking` + +- **Type:** `"render"` +- **Optional:** Yes + +Blocking behavior for the linked resource. + +### `color` + +- **Type:** `string` +- **Optional:** Yes + +Color hint for the linked resource. + +### `crossorigin` + +- **Type:** `string` +- **Optional:** Yes + +Cross-origin request mode. + +Common values include `""`, `"anonymous"`, and `"use-credentials"`. + +For request-mode details and credential behavior, see MDN's [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#crossorigin) reference. + +### `crossOrigin` + +- **Type:** `string` +- **Optional:** Yes + +Camel-case form of `crossorigin`. + +### `disabled` + +- **Type:** `boolean` +- **Default:** `false` +- **Optional:** Yes + +Whether the link is disabled. + +### `fetchpriority` + +- **Type:** `"high" | "low" | "auto"` +- **Default:** `"auto"` +- **Optional:** Yes + +Fetch priority hint. + +For priority values and fetch behavior, see MDN's [`fetchpriority`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#fetchpriority) reference. -Following this, include the emoji as an argument within that function in the `href` property of the Link component: +### `hreflang` -```jsx +- **Type:** `string` +- **Optional:** Yes + +Language of the linked resource. + +### `imagesizes` + +- **Type:** `string` +- **Optional:** Yes + +Sizes hint used with responsive image links. + +For syntax and responsive image selection behavior, see MDN's [`imagesizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#imagesizes) reference. + +### `imagesrcset` + +- **Type:** `string` +- **Optional:** Yes + +Source set used with responsive image links. + +For syntax and responsive image candidate behavior, see MDN's [`imagesrcset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#imagesrcset) reference. + +### `integrity` + +- **Type:** `string` +- **Optional:** Yes + +Subresource Integrity metadata. + +For integrity token syntax and validation behavior, see MDN's [`integrity`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#integrity) reference. + +### `media` + +- **Type:** `string` +- **Optional:** Yes + +Media condition for when the linked resource applies. + +For media query syntax and matching behavior, see MDN's [`media`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#media) reference. + +### `referrerpolicy` + +- **Type:** `string` +- **Default:** `"strict-origin-when-cross-origin"` +- **Optional:** Yes + +Referrer policy for requests made for the linked resource. + +Common values: + +| Value | Meaning | +| --- | --- | +| `"no-referrer"` | Do not send the `Referer` header. | +| `"no-referrer-when-downgrade"` | Send the referrer except when navigating from HTTPS to HTTP. | +| `"origin"` | Send only the origin as the referrer. | +| `"origin-when-cross-origin"` | Send the full referrer on same-origin requests and only the origin on cross-origin requests. | +| `"same-origin"` | Send the referrer on same-origin requests only. | +| `"strict-origin"` | Send only the origin when the security level stays the same, and send no referrer to less secure destinations. | +| `"strict-origin-when-cross-origin"` | Send the full referrer on same-origin requests, send only the origin on cross-origin requests when the security level stays the same, and send no referrer to less secure destinations. | +| `"unsafe-url"` | Send the origin and path as the referrer on all requests. | + +For the full set of policy values and their behavior, see MDN's [`referrerpolicy`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) reference. + +### `referrerPolicy` + +- **Type:** `string` +- **Default:** `"strict-origin-when-cross-origin"` +- **Optional:** Yes + +Camel-case form of `referrerpolicy`. + +### `sizes` + +- **Type:** `string` +- **Optional:** Yes + +Icon sizes metadata. + +For icon size syntax and matching behavior, see MDN's [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#sizes) reference. + +### `type` + +- **Type:** `string` +- **Optional:** Yes + +MIME type of the linked resource. + +For MIME type usage and processing details, see MDN's [`type`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#type) reference. + +## Behavior + +- `Link` requires a surrounding [`MetaProvider`](/solid-meta/reference/meta/metaprovider). +- `Link` tags append in render order. `@solidjs/meta` does not deduplicate them. +- During SSR, `Link` renders as a self-closing tag. + +## Examples + +### Basic usage + +```tsx import { MetaProvider, Link } from "@solidjs/meta"; -export default function Root() { +function App() { return ( - + ); } ``` + +## Related + +- [``](/solid-meta/reference/meta/metaprovider) +- [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/metaprovider.mdx b/src/routes/solid-meta/reference/meta/metaprovider.mdx index e1debf701..627b79556 100644 --- a/src/routes/solid-meta/reference/meta/metaprovider.mdx +++ b/src/routes/solid-meta/reference/meta/metaprovider.mdx @@ -2,8 +2,8 @@ title: MetaProvider order: 6 use_cases: >- - initializing meta tags, wrapping app, head management setup, meta context, - always in meta apps + head management setup, metadata context, SSR head collection, provider setup, + wrapping head tags tags: - provider - meta @@ -13,15 +13,83 @@ tags: - head version: "1.0" description: >- - MetaProvider wraps your Solid app to enable head tag management. Essential - parent component for all metadata components to function properly. + Provide the context used by `@solidjs/meta` components and `useHead`. --- -`MetaProvider` is a parent component responsible for wrapping all the metadata components. -All components that are contained within this will be added to the application `` +`MetaProvider` provides the context used to register and render head tags from `@solidjs/meta`. -```tsx twoslash +## Import + +```tsx +import { MetaProvider } from "@solidjs/meta"; +``` + +## Type + +```tsx +const MetaProvider: ParentComponent; +``` + +## Props + +### `children` + +- **Type:** `JSX.Element` +- **Optional:** No + +Tree that can render `@solidjs/meta` components or call [`useHead`](/solid-meta/reference/meta/use-head). + +## Behavior + +- `MetaProvider` is required. [`useHead`](/solid-meta/reference/meta/use-head) throws if no provider is found. +- On the server, `MetaProvider` collects registered tags and exposes them through Solid's asset pipeline with `useAssets`. +- In SSR output, those tags render where the app calls `getAssets()` from `solid-js/web`. +- On the client, tags rendered by `@solidjs/meta` are managed in `document.head`. +- During hydration, the provider reuses server-rendered tags marked with `data-sm`. +- On a client-only render, existing `data-sm` tags in `document.head` are removed before new tags are mounted. + +## Examples + +### Basic usage + +```tsx +import { MetaProvider, Title, Meta } from "@solidjs/meta"; + +function App() { + return ( + + Solid Docs + + + ); +} +``` + +### Server rendering with `getAssets()` + +```tsx +import { renderToString, getAssets } from "solid-js/web"; import { MetaProvider } from "@solidjs/meta"; +import App from "./App"; + +const html = renderToString(() => ( + + + +)); -// add meta components; +const documentHtml = ` + + ${getAssets()} +
${html}
+`; ``` + +## Related + +- [`useHead`](/solid-meta/reference/meta/use-head) +- [``](/solid-meta/reference/meta/title) +- [`<Meta />`](/solid-meta/reference/meta/meta) +- [`<Link />`](/solid-meta/reference/meta/link) +- [`<Style />`](/solid-meta/reference/meta/style) +- [`<Base />`](/solid-meta/reference/meta/base) diff --git a/templates/reference-component-template.mdx b/templates/reference-component-template.mdx new file mode 100644 index 000000000..ae8900400 --- /dev/null +++ b/templates/reference-component-template.mdx @@ -0,0 +1,66 @@ +--- +title: ComponentName +use_cases: >- + short phrases here +tags: + - component + - tag-two +version: "1.0" +description: >- + One-sentence factual description. +--- + +<!-- +Use this for: +- component reference pages + +Rules: +- Read the source first. +- Keep the intro definitional. +- Use a Type section for the exported props type. +- Do not use a props table. +- For each prop: Type, Default if applicable, then Optional. +- Behavior should cover runtime facts not already explained in Props. +--> + +`ComponentName` in a factual, brief definition. + +## Import + +```tsx +import { ComponentName } from "package-name"; +``` + +## Type + +```tsx +type ComponentNameProps = { + propName?: SomeType; +}; +``` + +## Props + +### `propName` + +- **Type:** `SomeType` +- **Default:** `someValue` +- **Optional:** Yes + +Short description. + +## Behavior + +- List of source-backed runtime fact. + +## Examples + +### Basic usage + +```tsx +// example +``` + +## Related (if applicable) + +- [Related API](/reference/...) diff --git a/templates/reference-function-template.mdx b/templates/reference-function-template.mdx new file mode 100644 index 000000000..e465bf6b3 --- /dev/null +++ b/templates/reference-function-template.mdx @@ -0,0 +1,72 @@ +--- +title: APIName +use_cases: >- + short phrases here +tags: + - tag-one + - tag-two +version: "1.0" +description: >- + One-sentence factual description. +--- + +<!-- +Use this for: +- functions +- hooks / primitives +- helpers +- response helpers + +Rules: +- Read the source first. +- Keep the intro definitional. +- Put signature facts in Type / Parameters / Return value. +- Put runtime consequences in Behavior. +- Do not repeat the same fact across sections. +- Use Type, then Default if applicable, then Required. +--> + +`APIName` is a factual simple definition. + +## Import + +```tsx +import { APIName } from "package-name"; +``` + +## Type + +```tsx +function APIName(param: SomeType): ReturnType; +``` + +## Parameters + +### `param` + +- **Type:** `SomeType` +- **Required:** Yes + +Short factual description. + +## Return value + +- **Type:** `ReturnType` + +Short factual description. + +## Behavior + +- List of source-backed runtime fact. + +## Examples + +### Basic usage + +```tsx +// example +``` + +## Related + +- [Related API](/reference/...) diff --git a/templates/reference-object-return-template.mdx b/templates/reference-object-return-template.mdx new file mode 100644 index 000000000..3e9705a59 --- /dev/null +++ b/templates/reference-object-return-template.mdx @@ -0,0 +1,76 @@ +--- +title: APIName +use_cases: >- + short phrases here +tags: + - tag-one + - tag-two +version: "1.0" +description: >- + One-sentence factual description. +--- + +<!-- +Use this for: +- APIs that return objects +- APIs that return tuple members with documented fields +- pages like useSubmission / useSubmissions / useLocation + +Rules: +- Read the source first. +- Keep the intro definitional. +- Do not use a return-value table when the fields need short explanations. +- For each return field: Type, Defined when if needed, then description. +- Use Defined when for values that may be undefined. +--> + +`APIName` is a factual brief definition. + +## Import + +```tsx +import { APIName } from "package-name"; +``` + +## Type + +```tsx +function APIName(): ReturnedType; +``` + +## Parameters + +`APIName` takes no arguments. + +## Return value + +`APIName` returns an object with the following properties: + +### `fieldName` + +- **Type:** `SomeType` +- **Defined when:** Condition, if needed. + +Short factual description. + +### `methodName` + +- **Type:** `() => void` + +Short factual description. + +## Behavior + +- List of source-backed runtime fact. + +## Examples + +### Basic usage + +```tsx +// example +``` + +## Related + +- [Related API](/reference/...) diff --git a/templates/reference-property-template.mdx b/templates/reference-property-template.mdx new file mode 100644 index 000000000..dd78713af --- /dev/null +++ b/templates/reference-property-template.mdx @@ -0,0 +1,63 @@ +--- +title: PropertyName +use_cases: >- + short phrases here +tags: + - tag-one + - tag-two +version: "1.0" +description: >- + One-sentence factual description. +--- + +<!-- +Use this for: +- route-definition properties +- JSX attribute reference pages +- property-style API surfaces + +Rules: +- Read the source first. +- Define what the property is and where it is used. +- Document the property type directly from source. +- Keep return-value language out unless the property itself returns something. +- Behavior should describe when the property is read and what effect it has. +--> + +`PropertyName` is a property used on `OwnerAPI`. + +## Import + +```tsx +import { OwnerAPI } from "package-name"; +``` + +## Type + +```tsx +type PropertyName = SomeType; +``` + +## Parameters + +### `propertyName` + +- **Type:** `SomeType` + +Short factual description. + +## Behavior + +- List of source-backed runtime fact. + +## Examples + +### Basic usage + +```tsx +// example +``` + +## Related + +- [Related API](/reference/...) From 7210e7536140ff1be38488c175c5acf48b9c1cc6 Mon Sep 17 00:00:00 2001 From: Sarah Gerrard <gerrardsarah@gmail.com> Date: Wed, 15 Apr 2026 17:55:55 -0700 Subject: [PATCH 3/7] update meta refs --- src/routes/solid-meta/reference/meta/base.mdx | 42 +--- src/routes/solid-meta/reference/meta/link.mdx | 206 +----------------- src/routes/solid-meta/reference/meta/meta.mdx | 48 ++-- .../reference/meta/metaprovider.mdx | 58 ++--- .../solid-meta/reference/meta/style.mdx | 60 +++-- .../solid-meta/reference/meta/title.mdx | 54 +++-- .../solid-meta/reference/meta/use-head.mdx | 185 ++++++++-------- 7 files changed, 244 insertions(+), 409 deletions(-) diff --git a/src/routes/solid-meta/reference/meta/base.mdx b/src/routes/solid-meta/reference/meta/base.mdx index 65331c629..acf5be624 100644 --- a/src/routes/solid-meta/reference/meta/base.mdx +++ b/src/routes/solid-meta/reference/meta/base.mdx @@ -2,19 +2,18 @@ title: Base order: 5 use_cases: >- - base URL, relative URL resolution, document base, target defaults + base urls, relative urls, link targets, document head tags: - base - - url - - meta - head - - routing + - url + - component version: "1.0" description: >- - Render a `base` element in the current `MetaProvider`. + Base renders a base element through Solid Meta. --- -`Base` renders a [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/base) element in the current [`MetaProvider`](/solid-meta/reference/meta/metaprovider) to set the document base URL or default browsing context for relative URLs and navigation targets. +`Base` adds a [`<base>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) element that sets the document base URL for resolving relative URLs. ## Import @@ -25,37 +24,18 @@ import { Base } from "@solidjs/meta"; ## Type ```tsx -function Base(props: JSX.BaseHTMLAttributes<HTMLBaseElement>): null; +const Base: Component<JSX.BaseHTMLAttributes<HTMLBaseElement>>; ``` ## Props -### `href` - -- **Type:** `string` -- **Optional:** Yes - -Document base URL. - -For URL resolution details, see MDN's [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base#href) reference. - -### `target` - -- **Type:** `string` -- **Default:** `"_self"` -- **Optional:** Yes - -Default browsing context for relative links and form submissions. - -Common values include `"_self"`, `"_blank"`, `"_parent"`, and `"_top"`. - -For browsing-context keywords and target behavior, see MDN's [`target`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base#target) reference. +Accepts attributes for [`<base>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base). ## Behavior -- `Base` requires a surrounding [`MetaProvider`](/solid-meta/reference/meta/metaprovider). -- `Base` is a void element. During SSR, `@solidjs/meta` renders it as a self-closing tag. -- `@solidjs/meta` does not deduplicate `Base` tags. If multiple `Base` components are rendered, it appends multiple `base` elements to `head`. +- Registers a self-closing `base` tag. +- Non-cascading tags can add one document-head element per active instance. +- Requires [`MetaProvider`](/solid-meta/reference/meta/metaprovider) in the component tree. ## Examples @@ -75,5 +55,5 @@ function App() { ## Related -- [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider) +- [`MetaProvider`](/solid-meta/reference/meta/metaprovider) - [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/link.mdx b/src/routes/solid-meta/reference/meta/link.mdx index f25c5531e..8c5119ee5 100644 --- a/src/routes/solid-meta/reference/meta/link.mdx +++ b/src/routes/solid-meta/reference/meta/link.mdx @@ -1,20 +1,19 @@ --- title: Link order: 2 -use_cases: "favicons, stylesheets, preload hints, canonical URLs, head links" +use_cases: >- + links, favicons, stylesheets, preloads, external resources tags: - link - - favicon - - stylesheet - - assets - head - resources + - component version: "1.0" description: >- - Render a `link` element in the current `MetaProvider`. + Link renders a link element through Solid Meta. --- -`Link` renders a [`link`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element in the current [`MetaProvider`](/solid-meta/reference/meta/metaprovider) to register an external resource or relationship in the document head. +`Link` adds a [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element that defines a relationship between the document and an external resource. ## Import @@ -25,201 +24,18 @@ import { Link } from "@solidjs/meta"; ## Type ```tsx -function Link(props: JSX.LinkHTMLAttributes<HTMLLinkElement>): null; +const Link: Component<JSX.LinkHTMLAttributes<HTMLLinkElement>>; ``` ## Props -### `href` - -- **Type:** `string` -- **Optional:** Yes - -Resource URL. - -### `rel` - -- **Type:** `string` -- **Optional:** Yes - -Relationship between the current document and the linked resource. -Value is a space-separated set of link-relation keywords. - -Common values: - -| Value | Meaning | -| --- | --- | -| `alternate` | Identifies an alternate representation of the current document. | -| `canonical` | Identifies the preferred URL for the current document. | -| `icon` | Identifies an icon for the current document. | -| `manifest` | Links a web app manifest. | -| `modulepreload` | Requests early loading of a JavaScript module graph. | -| `preconnect` | Requests an early connection to another origin. | -| `dns-prefetch` | Requests early DNS resolution for another origin. | -| `prefetch` | Hints that the resource may be needed for a future navigation. | -| `preload` | Hints that the resource is likely needed for the current navigation. | -| `stylesheet` | Identifies an external stylesheet. | - -For the full set of relation keywords, see MDN's [`rel`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#rel) reference. - -### `as` - -- **Type:** `string` -- **Optional:** Yes - -Resource destination type. - -Common values include `"audio"`, `"document"`, `"fetch"`, `"font"`, `"image"`, `"script"`, `"style"`, `"track"`, `"video"`, and `"worker"`. - -For the full set of destination values, see MDN's [`as`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#as) reference. - -### `blocking` - -- **Type:** `"render"` -- **Optional:** Yes - -Blocking behavior for the linked resource. - -### `color` - -- **Type:** `string` -- **Optional:** Yes - -Color hint for the linked resource. - -### `crossorigin` - -- **Type:** `string` -- **Optional:** Yes - -Cross-origin request mode. - -Common values include `""`, `"anonymous"`, and `"use-credentials"`. - -For request-mode details and credential behavior, see MDN's [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#crossorigin) reference. - -### `crossOrigin` - -- **Type:** `string` -- **Optional:** Yes - -Camel-case form of `crossorigin`. - -### `disabled` - -- **Type:** `boolean` -- **Default:** `false` -- **Optional:** Yes - -Whether the link is disabled. - -### `fetchpriority` - -- **Type:** `"high" | "low" | "auto"` -- **Default:** `"auto"` -- **Optional:** Yes - -Fetch priority hint. - -For priority values and fetch behavior, see MDN's [`fetchpriority`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#fetchpriority) reference. - -### `hreflang` - -- **Type:** `string` -- **Optional:** Yes - -Language of the linked resource. - -### `imagesizes` - -- **Type:** `string` -- **Optional:** Yes - -Sizes hint used with responsive image links. - -For syntax and responsive image selection behavior, see MDN's [`imagesizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#imagesizes) reference. - -### `imagesrcset` - -- **Type:** `string` -- **Optional:** Yes - -Source set used with responsive image links. - -For syntax and responsive image candidate behavior, see MDN's [`imagesrcset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#imagesrcset) reference. - -### `integrity` - -- **Type:** `string` -- **Optional:** Yes - -Subresource Integrity metadata. - -For integrity token syntax and validation behavior, see MDN's [`integrity`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#integrity) reference. - -### `media` - -- **Type:** `string` -- **Optional:** Yes - -Media condition for when the linked resource applies. - -For media query syntax and matching behavior, see MDN's [`media`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#media) reference. - -### `referrerpolicy` - -- **Type:** `string` -- **Default:** `"strict-origin-when-cross-origin"` -- **Optional:** Yes - -Referrer policy for requests made for the linked resource. - -Common values: - -| Value | Meaning | -| --- | --- | -| `"no-referrer"` | Do not send the `Referer` header. | -| `"no-referrer-when-downgrade"` | Send the referrer except when navigating from HTTPS to HTTP. | -| `"origin"` | Send only the origin as the referrer. | -| `"origin-when-cross-origin"` | Send the full referrer on same-origin requests and only the origin on cross-origin requests. | -| `"same-origin"` | Send the referrer on same-origin requests only. | -| `"strict-origin"` | Send only the origin when the security level stays the same, and send no referrer to less secure destinations. | -| `"strict-origin-when-cross-origin"` | Send the full referrer on same-origin requests, send only the origin on cross-origin requests when the security level stays the same, and send no referrer to less secure destinations. | -| `"unsafe-url"` | Send the origin and path as the referrer on all requests. | - -For the full set of policy values and their behavior, see MDN's [`referrerpolicy`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) reference. - -### `referrerPolicy` - -- **Type:** `string` -- **Default:** `"strict-origin-when-cross-origin"` -- **Optional:** Yes - -Camel-case form of `referrerpolicy`. - -### `sizes` - -- **Type:** `string` -- **Optional:** Yes - -Icon sizes metadata. - -For icon size syntax and matching behavior, see MDN's [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#sizes) reference. - -### `type` - -- **Type:** `string` -- **Optional:** Yes - -MIME type of the linked resource. - -For MIME type usage and processing details, see MDN's [`type`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#type) reference. +Accepts attributes for [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link). ## Behavior -- `Link` requires a surrounding [`MetaProvider`](/solid-meta/reference/meta/metaprovider). -- `Link` tags append in render order. `@solidjs/meta` does not deduplicate them. -- During SSR, `Link` renders as a self-closing tag. +- Registers a self-closing `link` tag. +- Non-cascading tags can add one document-head element per active instance. +- Requires [`MetaProvider`](/solid-meta/reference/meta/metaprovider) in the component tree. ## Examples @@ -239,5 +55,5 @@ function App() { ## Related -- [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider) +- [`MetaProvider`](/solid-meta/reference/meta/metaprovider) - [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/meta.mdx b/src/routes/solid-meta/reference/meta/meta.mdx index 27ed5cfc1..c42631930 100644 --- a/src/routes/solid-meta/reference/meta/meta.mdx +++ b/src/routes/solid-meta/reference/meta/meta.mdx @@ -2,38 +2,47 @@ title: Meta order: 3 use_cases: >- - seo optimization, social media tags, viewport settings, charset configuration, - open graph + metadata, descriptions, viewport tags, charset tags, social metadata tags: - meta - - seo - - viewport - - metadata - head - - tags + - metadata + - component version: "1.0" description: >- - Add SEO and viewport metadata to your Solid app with the Meta component. - Configure description, keywords, and social media tags for better reach. + Meta renders a meta element through Solid Meta. --- -The `<Meta>` component represents metadata that cannot be represented by other HTML elements. -It is a wrapper for the native [`meta`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) element and has the same properties. +`Meta` adds a [`<meta>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) element for metadata that is not represented by another HTML metadata element. + +## Import -```tsx twoslash +```tsx import { Meta } from "@solidjs/meta"; +``` + +## Type -<Meta name="description" content="My site description" />; +```tsx +const Meta: Component<JSX.MetaHTMLAttributes<HTMLMetaElement>>; ``` -`Meta` components can be placed in the [`MetaProvider`](/solid-meta/reference/meta/metaprovider) or added throughout the application for additional metadata or override parents. -`Meta` tags are considered the same and will be overridden if `name` attributes match. +## Props -## Usage +Accepts attributes for [`<meta>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta). -### Adding `meta` tag +## Behavior -```tsx twoslash {6-8} +- Registers a `meta` tag with self-closing server rendering. +- Cascading identity uses `name`, `http-equiv`, `content`, `charset`, `media`, and `property` from the tag props. +- `property` is treated as `name` when Solid Meta builds the tag key. +- Requires [`MetaProvider`](/solid-meta/reference/meta/metaprovider) in the component tree. + +## Examples + +### Basic usage + +```tsx import { MetaProvider, Meta } from "@solidjs/meta"; export default function Root() { @@ -46,3 +55,8 @@ export default function Root() { ); } ``` + +## Related + +- [`MetaProvider`](/solid-meta/reference/meta/metaprovider) +- [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/metaprovider.mdx b/src/routes/solid-meta/reference/meta/metaprovider.mdx index 627b79556..865947d37 100644 --- a/src/routes/solid-meta/reference/meta/metaprovider.mdx +++ b/src/routes/solid-meta/reference/meta/metaprovider.mdx @@ -2,21 +2,19 @@ title: MetaProvider order: 6 use_cases: >- - head management setup, metadata context, SSR head collection, provider setup, - wrapping head tags + head context, metadata context, document head management tags: - provider - meta - - setup - - context - - wrapper - head + - context + - component version: "1.0" description: >- - Provide the context used by `@solidjs/meta` components and `useHead`. + MetaProvider provides the context used by Solid Meta head tags. --- -`MetaProvider` provides the context used to register and render head tags from `@solidjs/meta`. +`MetaProvider` supplies the context that Solid Meta components and [`useHead`](/solid-meta/reference/meta/use-head) use to add head tags. ## Import @@ -35,18 +33,16 @@ const MetaProvider: ParentComponent; ### `children` - **Type:** `JSX.Element` -- **Optional:** No +- **Optional:** Yes -Tree that can render `@solidjs/meta` components or call [`useHead`](/solid-meta/reference/meta/use-head). +Content rendered inside the provider. ## Behavior -- `MetaProvider` is required. [`useHead`](/solid-meta/reference/meta/use-head) throws if no provider is found. -- On the server, `MetaProvider` collects registered tags and exposes them through Solid's asset pipeline with `useAssets`. -- In SSR output, those tags render where the app calls `getAssets()` from `solid-js/web`. -- On the client, tags rendered by `@solidjs/meta` are managed in `document.head`. -- During hydration, the provider reuses server-rendered tags marked with `data-sm`. -- On a client-only render, existing `data-sm` tags in `document.head` are removed before new tags are mounted. +- Creates a `MetaContext.Provider` for its children. +- On the client, active head tags are appended to `document.head` and removed during cleanup. +- During server rendering, rendered head tags are registered through `useAssets`. +- Solid Meta components and [`useHead`](/solid-meta/reference/meta/use-head) throw if they run without a `MetaProvider` in the component tree. ## Examples @@ -55,7 +51,7 @@ Tree that can render `@solidjs/meta` components or call [`useHead`](/solid-meta/ ```tsx import { MetaProvider, Title, Meta } from "@solidjs/meta"; -function App() { +export default function Root() { return ( <MetaProvider> <Title>Solid Docs @@ -65,31 +61,11 @@ function App() { } ``` -### Server rendering with `getAssets()` - -```tsx -import { renderToString, getAssets } from "solid-js/web"; -import { MetaProvider } from "@solidjs/meta"; -import App from "./App"; - -const html = renderToString(() => ( - - - -)); - -const documentHtml = ` - - ${getAssets()} -
${html}
-`; -``` - ## Related +- [`Title`](/solid-meta/reference/meta/title) +- [`Meta`](/solid-meta/reference/meta/meta) +- [`Link`](/solid-meta/reference/meta/link) +- [`Style`](/solid-meta/reference/meta/style) +- [`Base`](/solid-meta/reference/meta/base) - [`useHead`](/solid-meta/reference/meta/use-head) -- [``](/solid-meta/reference/meta/title) -- [`<Meta />`](/solid-meta/reference/meta/meta) -- [`<Link />`](/solid-meta/reference/meta/link) -- [`<Style />`](/solid-meta/reference/meta/style) -- [`<Base />`](/solid-meta/reference/meta/base) diff --git a/src/routes/solid-meta/reference/meta/style.mdx b/src/routes/solid-meta/reference/meta/style.mdx index eb66313a8..b7d05ff9f 100644 --- a/src/routes/solid-meta/reference/meta/style.mdx +++ b/src/routes/solid-meta/reference/meta/style.mdx @@ -1,45 +1,54 @@ --- title: Style order: 4 -use_cases: "inline styles, critical css, theme styles, dynamic styling, css-in-js" +use_cases: >- + style tags, inline css, document head tags: - style - - css - - inline - - styling - head + - css + - component version: "1.0" description: >- - Add inline CSS styles to your Solid app's head with the Style component. - Useful for critical CSS and dynamic styling needs in your application. + Style renders a style element through Solid Meta. --- -`Style` is a component that adds the [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element to your document's `head`. +`Style` adds a [`<style>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element for CSS rules that apply to the document. + +## Import -```tsx twoslash +```tsx import { Style } from "@solidjs/meta"; +``` + +## Type -<Style> - {` - body { - background-color: #000; - } - `} -</Style>; +```tsx +const Style: Component<JSX.StyleHTMLAttributes<HTMLStyleElement>>; ``` -## Usage +## Props + +Accepts attributes for [`<style>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style). -### Adding `style` tag +### `children` -The `Style` component can add CSS to style elements within your application. -It is recommended to add styles in an external stylesheet and use a `Link` instead, rather than using this component, however. +- **Type:** `JSX.Element` +- **Optional:** Yes -:::tip[Note] -Styles within the `Style` component are not scoped. -::: +Content rendered inside the `style` element. -```tsx twoslash +## Behavior + +- Registers a `style` tag with `close: true`. +- Non-cascading tags can add one document-head element per active instance. +- Requires [`MetaProvider`](/solid-meta/reference/meta/metaprovider) in the component tree. + +## Examples + +### Basic usage + +```tsx import { MetaProvider, Style } from "@solidjs/meta"; export default function Root() { @@ -54,3 +63,8 @@ export default function Root() { ); } ``` + +## Related + +- [`MetaProvider`](/solid-meta/reference/meta/metaprovider) +- [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/title.mdx b/src/routes/solid-meta/reference/meta/title.mdx index a22ca6e55..0f197fae0 100644 --- a/src/routes/solid-meta/reference/meta/title.mdx +++ b/src/routes/solid-meta/reference/meta/title.mdx @@ -2,39 +2,65 @@ title: Title order: 1 use_cases: >- - page titles, seo optimization, browser tab text, dynamic titles, navigation - context + page titles, document titles, browser tab text, head metadata tags: - title - - seo - head - meta - - browser + - component version: "1.0" description: >- - Set dynamic page titles in your Solid app with the Title component. Essential - for SEO and providing context in browser tabs and bookmarks. + Title renders a title element through Solid Meta. --- -`Title` is a component that renders the [`title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) element. -This will render the title of the page in the browser tab. +`Title` adds a [`<title>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) element that sets the document title. -```tsx twoslash +## Import + +```tsx import { Title } from "@solidjs/meta"; -<Title>My Site; ``` -## Usage +## Type + +```tsx +const Title: Component>; +``` + +## Props + +Accepts attributes for [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title). + +### `children` + +- **Type:** `JSX.Element` +- **Optional:** Yes -### Setting the title for your site +Content rendered inside the `title` element. -```tsx twoslash title="root.tsx" {5} +## Behavior + +- Registers a `title` tag with `close: true` and `escape: true`. +- Cascading keeps the latest active `title` instance in the document head and restores the previous instance when the latest one is removed. +- Requires [`MetaProvider`](/solid-meta/reference/meta/metaprovider) in the component tree. + +## Examples + +### Basic usage + +```tsx import { MetaProvider, Title } from "@solidjs/meta"; + export default function Root() { return ( <MetaProvider> - <Title>Default Application Title + Solid Docs ); } ``` + +## Related + +- [`MetaProvider`](/solid-meta/reference/meta/metaprovider) +- [`useHead`](/solid-meta/reference/meta/use-head) diff --git a/src/routes/solid-meta/reference/meta/use-head.mdx b/src/routes/solid-meta/reference/meta/use-head.mdx index c297d9a7e..ed8f062ba 100644 --- a/src/routes/solid-meta/reference/meta/use-head.mdx +++ b/src/routes/solid-meta/reference/meta/use-head.mdx @@ -2,32 +2,28 @@ title: useHead order: 7 use_cases: >- - custom head tags, scripts, json-ld, arbitrary head elements, dynamic metadata, - ssr head management + custom head tags, scripts, json-ld, arbitrary head elements, head metadata tags: - usehead - head - meta - - script - - json-ld - - ssr + - primitive version: "1.0" description: >- - useHead inserts custom elements into document head with fine-grained control, - including scripts and JSON-LD, while staying SSR-ready. + useHead adds a custom head tag through Solid Meta. --- -`useHead` is a low-level API for registering custom `` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider). +`useHead` adds a custom head tag from a `TagDescription` object. ## Import -```ts +```tsx import { useHead } from "@solidjs/meta"; ``` ## Type -```ts +```tsx type TagDescription = { tag: string; props: Record; @@ -45,139 +41,152 @@ function useHead(tag: TagDescription): void; ## Parameters -### `tag` +### Description object + +- **Parameter:** `tag` +- **Type:** `TagDescription` +- **Required:** Yes + +The object passed to `useHead`. + +#### `tag` - **Type:** `string` - **Required:** Yes -The tag name to render in `` (eg. `