<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# ShareButton

A button that shares a link: through the system's share sheet where there is one (phones, Safari), and by copying it where there is not, when it says "Link copied" for two seconds and screen readers hear it once. It shares the page's own address unless given `url`.

```tsx
import { ShareButton } from "@/components/ouro/share-button/share-button";
```

## Example

```tsx
<ShareButton url={`https://example.com/notes/${note.id}`} title={note.title} />
```

## Use instead when

- Use `CopyButton` instead to copy any text without a share sheet, and the `share()` helper for a share action inside a menu.

## Props

Type: `ShareButtonProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Layout only: margins, grid placement (`ms-auto`). Appearance classes warn in development. |
| `copiedLabel` | `string` | `"Link copied"` | What it says, and screen readers hear, when there was no share sheet and the link was copied instead. |
| `failedLabel` | `string` | `"Couldn't share"` | What it says, and screen readers hear, when neither sharing nor copying worked. |
| `hideLabel` | `boolean` |  | Shows only the icon; the label stays the button's name for screen readers. |
| `label` | `string` | `"Share"` | The button's label, and its name for screen readers with `hideLabel`. |
| `onShare` | `((result: ShareResult) => void)` |  | Called with how the share ended: `shared`, `copied`, `cancelled` or `failed`. |
| `ref` | `Ref<HTMLButtonElement>` |  | Reaches the rendered element. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control size, as Button's. |
| `text` | `string` |  | A line about the link, where the receiving app takes one. |
| `title` | `string` |  | A title for the link, where the receiving app takes one. |
| `url` | `string` | the page's own address | The address to share. |
| `variant` | `"solid" \| "soft" \| "outline" \| "plain"` | `"outline"` | Visual weight, as Button's. |

## Native attributes

Also accepts the attributes in React's `ButtonHTMLAttributes` and `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `children`: Not a prop. The label is `label`: `<ShareButton label="Share recipe" />`.
- `href`: Not a prop. The address is `url`: `<ShareButton url={link} />`.
- `onClick`: Not a prop. ShareButton shares on click itself; to react to it, pass `onShare`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: ShareButton merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

[^layout-classes]: test:registry/ouro/components/ouro/share-button/share-button.test.tsx::ShareButton > forwards a ref, takes button attributes, and lets app layout classes win verify:testExists(registry/ouro/components/ouro/share-button/share-button.test.tsx::ShareButton > forwards a ref, takes button attributes, and lets app layout classes win)