Merge pull request #22590 from jonthenerd/patch-1

docs: add information about @storybook/preview-api useArgs hook

docs/snippets/react/page-story-args-within-story.js.mdx

@@ -0,0 +1,31 @@
+```js
+// my-component/component.stories.js|jsx
+
+import { useArgs } from '@storybook/preview-api';
+import { Checkbox } from './checkbox';
+
+export default {
+  title: 'Inputs/Checkbox',
+  component: Checkbox,
+};
+
+export const Example = {
+  args: {
+    isChecked: false,
+    label: 'Try Me!',
+  },
+  /**
+   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
+   * If you are not concerned with linting, you may use an arrow function.
+   */
+  render: function Render(args) {
+    const [{ isChecked }, updateArgs] = useArgs();
+
+    function onChange() {
+      updateArgs({ isChecked: !isChecked });
+    }
+
+    return <Checkbox {...args} onChange={onChange} isChecked={isChecked} />;
+  },
+};
+```

docs/snippets/react/page-story-args-within-story.ts-4-9.mdx

@@ -0,0 +1,35 @@
+```ts
+// my-component/component.stories.ts|tsx
+
+import { StoryObj, Meta } from '@storybook/react';
+import { useArgs } from '@storybook/preview-api';
+import { Checkbox } from './checkbox';
+
+const meta = {
+  title: 'Inputs/Checkbox',
+  component: Checkbox,
+} satisfies Meta<typeof Checkbox>;
+export default meta;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Example = {
+  args: {
+    isChecked: false,
+    label: 'Try Me!',
+  },
+  /**
+   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
+   * If you are not concerned with linting, you may use an arrow function.
+   */
+  render: function Render(args) {
+    const [{ isChecked }, updateArgs] = useArgs();
+
+    function onChange() {
+      updateArgs({ isChecked: !isChecked });
+    }
+
+    return <Checkbox {...args} onChange={onChange} isChecked={isChecked} />;
+  },
+} satisfies Story;
+```

docs/snippets/react/page-story-args-within-story.ts.mdx

@@ -0,0 +1,35 @@
+```ts
+// my-component/component.stories.ts|tsx
+
+import { StoryObj, Meta } from '@storybook/react';
+import { useArgs } from '@storybook/preview-api';
+import { Checkbox } from './checkbox';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Inputs/Checkbox',
+  component: Checkbox,
+};
+export default meta;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Example: Story = {
+  args: {
+    isChecked: false,
+    label: 'Try Me!',
+  },
+  /**
+   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
+   * If you are not concerned with linting, you may use an arrow function.
+   */
+  render: function Render(args) {
+    const [{ isChecked }, updateArgs] = useArgs();
+
+    function onChange() {
+      updateArgs({ isChecked: !isChecked });
+    }
+
+    return <Checkbox {...args} onChange={onChange} isChecked={isChecked} />;
+  },
+};
+```

docs/writing-stories/args.md

@@ -213,6 +213,25 @@ Similarly, special formats are available for dates and colors. Date objects will
 
 Args specified through the URL will extend and override any default values of args set on the story.
 
+<IfRenderer renderer='react'>
+
+## Setting args from within a story
+
+Interactive components often need to be controlled by their containing component or page to respond to events, modify their state and reflect those changes in the UI. For example, when a user toggles a switch component, the switch should be checked, and the arg shown in Storybook should reflect the change. To enable this, you can use the `useArgs` API exported by `@storybook/preview-api`:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[    
+    'react/page-story-args-within-story.js.mdx',
+    'react/page-story-args-within-story.ts.mdx'
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+</IfRenderer>
+
 ## Mapping to complex arg values
 
 Complex values such as JSX elements cannot be serialized to the manager (e.g., the Controls addon) or synced with the URL. Arg values can be "mapped" from a simple string to a complex type using the `mapping` property in `argTypes` to work around this limitation. It works in any arg but makes the most sense when used with the `select` control type.