Button

A button component that can be rendered as another tag or focusable when disabled.

import * as React from 'react';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

export default function ExampleButton() {
  return <Button className={styles.Button}>Submit</Button>;
}

Usage guidelines

Submit buttons: Unlike the native button element, type="submit" must be specified on Button for it to act as a submit button.
Links: The Button component enforces button semantics (role="button", keyboard interaction, disabled state). It should not be used for links. See Rendering links as buttons below.
Async work: Use clickAction instead of onClick for async work so React manages pending state. See Async.

Anatomy

Import the component:

Anatomy

import { Button } from '@base-ui/react/button';

<Button />

Examples

Rendering as another tag

The button can remain keyboard accessible while being rendered as another tag, such as a <div>, by specifying nativeButton={false}.

Custom tag button

import { Button } from '@base-ui/react/button';

<Button render={<div />} nativeButton={false}>
  Button that can contain complex children
</Button>

The Button component enforces button semantics. nativeButton={false} signals that the rendered tag is not a <button>, but it must still be a tag that can receive button semantics (role="button", keyboard interaction handlers). Links (<a>) have their own semantics and should not be rendered as buttons through the render prop.

If a link needs to look like a button visually, style the <a> element directly with CSS rather than using the Button component.

Loading states

For buttons that enter a loading state after being clicked, specify the focusableWhenDisabled prop to ensure focus remains on the button when it becomes disabled. This prevents focus from being lost and maintains the tab order.

index.tsx index.module.css

'use client';
import * as React from 'react';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

export default function ExampleButton() {
  const [loading, setLoading] = React.useState(false);

  return (
    <Button
      className={styles.Button}
      disabled={loading}
      focusableWhenDisabled
      onClick={() => {
        setLoading(true);
        setTimeout(() => {
          setLoading(false);
        }, 4000);
      }}
    >
      {loading ? 'Submitting' : 'Submit'}
    </Button>
  );
}

Async

Use the clickAction prop for click handlers that perform async work. Base UI runs the action in a React transition and ignores repeated activations while the returned promise is pending.

See the Async Actions guide for details.

No changes saved

index.tsx index.module.css

'use client';
import * as React from 'react';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

interface SaveState {
  savedAt: string | null;
}

const initialState: SaveState = {
  savedAt: null,
};

async function saveProfile(): Promise<SaveState> {
  await wait(1000);

  return {
    savedAt: new Date().toLocaleTimeString([], {
      hour: '2-digit',
      minute: '2-digit',
      second: '2-digit',
    }),
  };
}

export default function ExampleButton() {
  const [state, saveAction, isPending] = React.useActionState(saveProfile, initialState);
  let status = 'No changes saved';

  if (isPending) {
    status = 'Saving changes...';
  } else if (state.savedAt) {
    status = `Saved at ${state.savedAt}`;
  }

  return (
    <div className={styles.Field}>
      <Button
        className={styles.Button}
        clickAction={() => saveAction()}
        disabled={isPending}
        focusableWhenDisabled
      >
        {isPending ? 'Saving profile' : 'Save profile'}
      </Button>
      <p className={styles.Status} aria-live="polite">
        {status}
      </p>
    </div>
  );
}

function wait(delay: number) {
  return new Promise<void>((resolve) => {
    setTimeout(resolve, delay);
  });
}

API reference

clickActionfunction—

Name: clickAction
Description: Event handler called when the button is activated. The action is run in a React transition when supported.
Type: | (( event: React.MouseEvent<HTMLElement, MouseEvent>, ) => void | PromiseLike<unknown>) | undefined

focusableWhenDisabledbooleanfalse

Name: focusableWhenDisabled
Description: Whether the button should be focusable when disabled.
Type: boolean | undefined
Default: false

nativeButtonbooleantrue

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).
Type: boolean | undefined
Default: true

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Button.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Button.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Button.State, ) => ReactElement) | undefined

data-disabled

Present when the button is disabled.

Attribute	Description	-
`data-disabled`	Present when the button is disabled.

Button.PropsHide

Re-Export of Button props as ButtonProps

Button.StateHide

type ButtonState = {
  /** Whether the button should ignore user interaction. */
  disabled: boolean;
}