mirror of
https://github.com/langgenius/dify.git
synced 2026-10-04 13:47:55 +08:00
106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
# Button
|
|
|
|
Use `Button` for an action with a visible text label. Use [`IconButton`] for an icon-only
|
|
command, `Toggle` for a persistent pressed state, and a native link when activation navigates to
|
|
a URL.
|
|
|
|
Dify UI `Button` is an opinionated wrapper around [Base UI Button]. It adds Dify variants,
|
|
sizes, content spacing, and a `loading` state while preserving the upstream button, focus, and
|
|
composition behavior.
|
|
|
|
## Button semantics
|
|
|
|
`Button` renders a native `<button type="button">` by default. Set `type="submit"` explicitly
|
|
when the button submits a form:
|
|
|
|
```tsx
|
|
<form onSubmit={handleSubmit}>
|
|
<Button type="submit">Save</Button>
|
|
</form>
|
|
```
|
|
|
|
Do not render a link through `Button`. Base UI applies button semantics, keyboard interaction,
|
|
and disabled behavior to the rendered element. Keep navigation on a native anchor or routing
|
|
link and reuse only the visual variants:
|
|
|
|
```tsx
|
|
<a className={buttonVariants({ variant: 'secondary' })} href="/settings">
|
|
Settings
|
|
</a>
|
|
```
|
|
|
|
Use `render` with `nativeButton={false}` only when a non-button element intentionally needs
|
|
button semantics. It is not a link mode.
|
|
|
|
## Loading and disabled states
|
|
|
|
`disabled` and `loading` describe different facts:
|
|
|
|
| Prop | Meaning | Default focus behavior |
|
|
| ---------- | -------------------------------------------- | ----------------------------------------------------- |
|
|
| `disabled` | The action is unavailable. | Native-disabled and removed from the tab order. |
|
|
| `loading` | The action was triggered and is now pending. | Activation is blocked while the button retains focus. |
|
|
|
|
`loading` owns Base UI's disabled interaction, retained focus, and the decorative spinner. The
|
|
button remains in the tab order with `aria-disabled`, and Dify UI suppresses activation. Pass the
|
|
pending state only to `loading`; keep independent availability conditions in `disabled`:
|
|
|
|
```tsx
|
|
<Button loading={isSaving} disabled={!canManageSettings}>
|
|
Save
|
|
</Button>
|
|
```
|
|
|
|
Pass `focusableWhenDisabled={false}` only when a loading button should opt into native disabled
|
|
behavior and may leave the tab order.
|
|
|
|
### Accessible loading feedback
|
|
|
|
The spinner is decorative. Keep a non-empty visible label throughout loading. If the visible label
|
|
stays the same, its text continues to name the button.
|
|
|
|
When the label changes while the focused button enters loading, give the changing text a stable ID
|
|
and reference it explicitly. Some browser and screen-reader combinations do not reliably announce
|
|
changes to a focused button's descendant text:
|
|
|
|
```tsx
|
|
const labelId = useId()
|
|
|
|
<Button loading={isSaving} aria-labelledby={labelId}>
|
|
<span id={labelId}>{isSaving ? 'Saving' : 'Save'}</span>
|
|
</Button>
|
|
```
|
|
|
|
The consumer owns this relationship because only it knows whether the label changes and whether
|
|
other visible context must also be referenced. Do not replace the changing text with `aria-label`.
|
|
|
|
`Button` does not add `aria-busy`: [WAI-ARIA `aria-busy`] describes an element whose own updates may
|
|
be deferred by assistive technology, not a generic pending action. Long-running announcements and
|
|
progress remain with the feature's status, live-region, or progress owner.
|
|
|
|
## Content and spacing
|
|
|
|
`Button` owns spacing between its direct children. Do not add icon margins or a standard `gap-*`
|
|
at call sites:
|
|
|
|
```tsx
|
|
<Button>
|
|
<span aria-hidden="true" className="i-ri-rocket-line size-4" />
|
|
Launch
|
|
</Button>
|
|
```
|
|
|
|
Regular (`medium`) and `large` sizes use 4px and 6px gaps. `small` uses 3px for `primary` and 4px
|
|
for the other variants. Use a `className` override only for a documented layout exception.
|
|
|
|
## Related guides
|
|
|
|
- Read [`IconButton`] for icon-only actions.
|
|
- Read [Accessible names and descriptions] when choosing or changing a naming source.
|
|
- Read [Base UI Button] for the upstream interaction and composition contract.
|
|
|
|
[Accessible names and descriptions]: ../../docs/accessible-names-and-descriptions.md
|
|
[Base UI Button]: https://base-ui.com/react/components/button
|
|
[WAI-ARIA `aria-busy`]: https://www.w3.org/TR/wai-aria#aria-busy
|
|
[`IconButton`]: ../icon-button/README.md
|