# Compound button

A compound button includes a main title and an additional description of the title. Use it when it’s helpful to include more detail.

## Best practices

### Do

- Use buttons for actions.
- Use active language that reflects the action that will happen next.
- Be brief. Usually a single verb is best, but include a noun if it increases clarity.
- Use sentence case and no end punctuation.

### Don't

- Hide buttons.
- Use articles such as “a,” “an,” or “the.”
- Use punctuation.
- Use an icon in a call-to-action button.

## Behavior and states

- A compound button includes a main title and an additional description of the title.
- Use a compound button when it’s helpful to include more detail.
- Compound buttons can have toggle behavior.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { CompoundButtonProps } from "@coreai-ds/react-components";
import type { JSXElement } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import { CalendarMonthRegular } from "@fluentui/react-icons";
import * as React from 'react';

// Inline wrapper so RCM resolves CompoundButton props and this meta owns
// `Default` (the fork-id dedup in main.ts drops the vendored duplicate).
export const Default = (props: CompoundButtonProps): JSXElement => (<CompoundButton icon={<CalendarMonthRegular />} secondaryContent="Secondary content" {...props}>
    Example
  </CompoundButton>);

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### CompoundButton API

```ts
interface CompoundButtonProps {
  /**
   * A button can have its content and borders styled for greater emphasis or to be subtle.
   * - 'secondary' (default): Gives emphasis to the button in such a way that it indicates a secondary action.
   * - 'primary': Emphasizes the button as a primary action.
   * - 'outline': Removes background styling.
   * - 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
   * - 'transparent': Removes background and border styling.
   * @default 'secondary'
   */
  appearance?: "outline" | "subtle" | "secondary" | "primary" | "transparent";

  as?: "a" | "button";

  children?: any;

  className?: string;

  /**
   * Container that wraps the children and the secondaryContent slot.
   */
  contentContainer?: NonNullable<WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * A button can show that it cannot be interacted with.
   * @default false
   */
  disabled?: boolean;

  /**
   * When set, allows the button to be focusable even when it has been disabled.
   * This is used in scenarios where it is important to keep a consistent tab order
   * for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * When set, allows the button to be focusable even when it has been disabled. This is used in scenarios where it
   * is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this
   * pattern is when the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.
   * @default false
   * false
   */
  disabledFocusable?: boolean;

  /**
   * Icon that renders either before or after the `children` as specified by the `iconPosition` prop.
   */
  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A button can format its icon to appear before or after its content.
   * @default 'before'
   */
  iconPosition?: "before" | "after";

  ref?: Ref<HTMLAnchorElement | HTMLButtonElement>;

  /**
   * Second line of text that describes the action this button takes.
   */
  secondaryContent?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A button can be rounded, circular, or square.
   * @default 'circular'
   */
  shape?: "circular" | "rounded" | "square";

  /**
   * A button supports different sizes.
   * @default 'medium'
   */
  size?: "small" | "medium" | "large";

  style?: CSSProperties;
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

## Appearance

Source: Fluent, adapted for CoreAI.

- `(undefined)`: the compound button appears with the default style
- `primary`: emphasizes the compound button as a primary action.
- `outline`: removes background styling.
- `subtle`: minimizes emphasis to blend into the background until hovered or focused
- `transparent`: removes background and border styling.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--appearance.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import { CalendarMonthRegular } from "@fluentui/react-icons";
import { bundleIcon } from "@fluentui/react-icons";
import { CalendarMonthFilled } from "@fluentui/react-icons";
import * as React from 'react';

const useStyles = makeStyles({
    wrapper: {
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
});

const CalendarMonth = bundleIcon(CalendarMonthFilled, CalendarMonthRegular);

export const Appearance = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.wrapper}>
      <CompoundButton secondaryContent="Secondary content" icon={<CalendarMonthRegular />}>
        Default
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" appearance="primary" icon={<CalendarMonthRegular />}>
        Primary
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" appearance="outline" icon={<CalendarMonth />}>
        Outline
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" appearance="subtle" icon={<CalendarMonth />}>
        Subtle
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" appearance="transparent" icon={<CalendarMonth />}>
        Transparent
      </CompoundButton>
    </div>);
};

export default Appearance;
```

## Disabled

Source: Fluent, adapted for CoreAI.

A compound button can be `disabled` or `disabledFocusable`.
              `disabledFocusable` is used in scenarios where it is important to keep a consistent tab order
              for screen reader and keyboard users. The primary example of this pattern is when
              the disabled compound button is in a menu or a commandbar and is seldom used for standalone buttons.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--disabled.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    innerWrapper: {
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
    outerWrapper: {
        display: 'flex',
        flexDirection: 'column',
        rowGap: '15px',
    },
});

export const Disabled = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.outerWrapper}>
      <div className={styles.innerWrapper}>
        <CompoundButton secondaryContent="Secondary content">Enabled state</CompoundButton>
        <CompoundButton disabled secondaryContent="Secondary content">
          Disabled state
        </CompoundButton>
        <CompoundButton disabledFocusable secondaryContent="Secondary content">
          Disabled focusable state
        </CompoundButton>
      </div>
      <div className={styles.innerWrapper}>
        <CompoundButton appearance="primary" secondaryContent="Secondary content">
          Enabled state
        </CompoundButton>
        <CompoundButton appearance="primary" disabled secondaryContent="Secondary content">
          Disabled state
        </CompoundButton>
        <CompoundButton appearance="primary" disabledFocusable secondaryContent="Secondary content">
          Disabled focusable state
        </CompoundButton>
      </div>
    </div>);
};

export default Disabled;
```

## Icon

Source: Fluent, adapted for CoreAI.

The CompoundButton has an `icon` slot that, if specified, renders an icon either `before` or `after` the children, as specified by the `iconPosition` prop.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--icon.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import { CalendarMonthRegular } from "@fluentui/react-icons";
import { Tooltip } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    wrapper: {
        alignItems: 'center',
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
});

export const Icon = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.wrapper}>
      <CompoundButton secondaryContent="Secondary content" icon={<CalendarMonthRegular />}>
        With calendar icon before contents
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" icon={<CalendarMonthRegular />} iconPosition="after">
        With calendar icon after contents
      </CompoundButton>
      <Tooltip content="With calendar icon only" relationship="label">
        <CompoundButton icon={<CalendarMonthRegular />}/>
      </Tooltip>
    </div>);
};

export default Icon;
```

## Shape

Source: Fluent, adapted for CoreAI.

A compound button can be rounded, circular, or square.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--shape.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    wrapper: {
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
});

export const Shape = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.wrapper}>
      <CompoundButton secondaryContent="Secondary content">Rounded</CompoundButton>
      <CompoundButton secondaryContent="Secondary content" shape="circular">
        Circular
      </CompoundButton>
      <CompoundButton secondaryContent="Secondary content" shape="square">
        Square
      </CompoundButton>
    </div>);
};

export default Shape;
```

## Size

Source: Fluent, adapted for CoreAI.

A compound button supports `small`, `medium` and `large` size. Default size is `medium`.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--size.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import { CalendarMonthRegular } from "@fluentui/react-icons";
import * as React from 'react';

const useStyles = makeStyles({
    wrapper: {
        alignItems: 'center',
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
});

export const Size = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.wrapper}>
      <CompoundButton icon={<CalendarMonthRegular />} secondaryContent="Secondary content" size="small">
        Size: small
      </CompoundButton>
      <CompoundButton icon={<CalendarMonthRegular />} secondaryContent="Secondary content" size="medium">
        Size: medium
      </CompoundButton>
      <CompoundButton icon={<CalendarMonthRegular />} secondaryContent="Secondary content" size="large">
        Size: large
      </CompoundButton>
    </div>);
};

export default Size;
```

## With Long Text

Source: Fluent, adapted for CoreAI.

Text wraps after it hits the max width of the component.

[Download source](/coreai-design-system/source/examples/components-button-compoundbutton--with-long-text.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { CompoundButton } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    longText: {
        width: '280px',
    },
    wrapper: {
        alignItems: 'center',
        columnGap: '15px',
        display: 'flex',
        minWidth: 'min-content',
    },
});

export const WithLongText = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.wrapper}>
      <CompoundButton secondaryContent="Secondary content">Short text</CompoundButton>
      <CompoundButton className={styles.longText} secondaryContent="Secondary content">
        Long text wraps after it hits the max width of the component
      </CompoundButton>
    </div>);
};

export default WithLongText;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=161008-6469)
- [Fluent button guidance](https://fluent2.microsoft.design/components/web/react/core/button/usage)