From a2bc0f5f7de56c19632d85c96f688f5d78ac678a Mon Sep 17 00:00:00 2001
From: Matei Trandafir <catalin_trand2@yahoo.com>
Date: Mon, 13 May 2024 19:18:57 +0300
Subject: [PATCH] Add documentation for svelte/elements (#11587)

closes #11451
---
 .../routes/docs/content/01-api/05-imports.md  | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md b/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
index c021915ea9..ca3c2fc9e1 100644
--- a/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
+++ b/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
@@ -107,3 +107,46 @@ const result = render(App, {
 	props: { some: 'property' }
 });
 ```
+
+## `svelte/elements`
+
+Svelte provides built-in [DOM types](https://github.com/sveltejs/svelte/blob/master/packages/svelte/elements.d.ts). A common use case for DOM types is forwarding props to an HTML element. To properly type your props and get full intellisense, your props interface should extend the attributes type for your HTML element:
+
+```svelte
+<script lang="ts">
+	import { HTMLAttributes } from 'svelte/elements';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		username: string;
+	}
+
+	let { username, ...rest }: Props = $props();
+</script>
+
+<div {...rest}>
+	Hi, {username}!
+</div>
+```
+
+> You can use `ComponentProps<ImportedComponent>`, if you wish to forward props to forward props to a Svelte component.
+
+Svelte provides a best-effort of all the HTML DOM types that exist. If an attribute is missing from our [type definitions](https://github.com/sveltejs/svelte/blob/master/packages/svelte/elements.d.ts), you are welcome to open an issue and/or a PR fixing it. For experimental attributes, you can augment the existing types locally by creating a `.d.ts` file:
+
+```ts
+import { HTMLButtonAttributes } from 'svelte/elements';
+
+declare module 'svelte/elements' {
+	export interface SvelteHTMLElements {
+		'custom-button': HTMLButtonAttributes;
+	}
+
+	// allows for more granular control over what element to add the typings to
+	export interface HTMLButtonAttributes {
+		veryexperimentalattribute?: string;
+	}
+}
+
+export {}; // ensure this is not an ambient module, else types will be overridden instead of augmented
+```
+
+The `.d.ts` file must be included in your `tsconfig.json` file. If you are using the standard `"include": ["src/**/*"]`, this just means the file should be placed in the `src` directory.