From 1114c4f024dc66dbe59ca0a27fc2626ece8cee54 Mon Sep 17 00:00:00 2001
From: metonym <ericyl.us@gmail.com>
Date: Mon, 23 Oct 2023 09:40:18 -0700
Subject: [PATCH] docs(button): add "Programmatic focus" example

Related #1830
---
 docs/src/pages/components/Button.svx              | 10 +++++++++-
 .../pages/framed/Button/ProgrammaticFocus.svelte  | 15 +++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/pages/framed/Button/ProgrammaticFocus.svelte

diff --git a/docs/src/pages/components/Button.svx b/docs/src/pages/components/Button.svx
index 4ddece95ff..45635bbc71 100644
--- a/docs/src/pages/components/Button.svx
+++ b/docs/src/pages/components/Button.svx
@@ -159,4 +159,12 @@ Set `expressive` to `true` to use Carbon's expressive typesetting.
 <Button size="lg" skeleton />
 <Button skeleton />
 <Button skeleton size="field" />
-<Button skeleton size="small" />
\ No newline at end of file
+<Button skeleton size="small" />
+
+## Programmatic focus
+
+Bind to the `ref` prop to access a reference to the underlying button element.
+
+You can use this reference to programmatically focus the button.
+
+<FileSource src="/framed/Button/ProgrammaticFocus" />
diff --git a/docs/src/pages/framed/Button/ProgrammaticFocus.svelte b/docs/src/pages/framed/Button/ProgrammaticFocus.svelte
new file mode 100644
index 0000000000..5040808a63
--- /dev/null
+++ b/docs/src/pages/framed/Button/ProgrammaticFocus.svelte
@@ -0,0 +1,15 @@
+<script>
+  import { Button } from "carbon-components-svelte";
+
+  let ref;
+</script>
+
+<Button bind:ref>Primary button</Button>
+<Button
+  kind="ghost"
+  on:click="{() => {
+    ref?.focus();
+  }}"
+>
+  Click to focus the Primary button
+</Button>