[Button] Add support for anchor tag attributes in Button component

[Kartik-Murthy]

Summary:

This PR enhances the Button component by adding support for anchor-specific attributes like href, target, rel, and download when the component is rendered as an anchor tag. It ensures correct TypeScript typing for these attributes and fixes type errors when target and download are used without href.

Related Issue: #45729

(You can refer to the issue for more details, including the provided Stackblitz example and image.)

Reproduction:

You can test the behavior using the original Stackblitz example provided by the author here:
Stackblitz Example

Changes:

• Updated ButtonProps to support anchor tag attributes when href is provided.
• Added type constraints to ensure proper type handling.
• Fixed TypeScript errors related to the invalid usage of target, download, or other anchor-specific attributes without href.
• Updated and added tests to ensure the correct behavior of anchor props in the Button component.

Testing:

• Tests have been added to verify that the Button component behaves correctly when used with anchor-specific attributes.

• Type errors are now correctly thrown when target or download is used without href.

• All related tests pass, including edge cases where component="a" is used with anchor attributes.

• I have followed (at least) the PR section of the contributing guide.

• I have tested the changes in this PR.

[mui-bot]

Netlify deploy preview

https://deploy-preview-45765--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against e92ec49

[siriwatknp]

Is this all of anchor attributes? How do we ensure that this is enough 🤔.

To be honest, I don't lean on this solution that much. I would update the docs on how to apply these props to the Button instead.

[Kartik-Murthy]

You're absolutely right about the anchor attributes—creating an explicit list does risk missing some attributes or falling out of sync with future HTML specs. I really appreciate your suggestion to focus on documentation instead.

As an alternative approach that doesn’t require listing specific attributes, we could document this pattern:

import { Button, ButtonProps } from '@mui/material';

// This correctly adds all anchor props only when href is present
type CustomButtonProps<C extends React.ElementType = 'button'> = ButtonProps<C, {}> &
  (({ href: string } & React.ComponentProps<'a'>) | { href: never });

export const CustomButton = (props: CustomButtonProps) => {
  return <Button {...props} />;
};

This approach leverages TypeScript's built-in types to automatically include all anchor attributes, helping us stay aligned with future HTML specs while minimizing maintenance overhead.

I hadn’t considered that earlier, but it’s a great idea, and I’m definitely on board with it. Would it make sense to close my PR and open a new one that addresses issue #45729 by updating the documentation instead of modifying the type definitions?

@siriwatknp @ZeeshanTamboli , I’d love to get your input on whether this seems like the best course of action.

[ZeeshanTamboli]

Before adding docs, we should first understand why the target attribute isn't supported on custom buttons that are wrapped with Material UI Buttons in TS.

[Kartik-Murthy]

I think the issue with target not being properly recognized on custom button component lies with the ButtonProps, though I'm not entirely certain about all the details.

ButtonProps type definition:-

export type ButtonProps
  RootComponent extends React.ElementType = ButtonTypeMap['defaultComponent'],
  AdditionalProps = {},
> = OverrideProps<ButtonTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType;
}

This definition doesn't seem to explicitly include the anchor element attributes like target when an href is provided.

What's interesting is that the ExtendButtonBase type in ButtonBase.d.ts file does seem to handle anchor transformation:

export type ExtendButtonBase<TypeMap extends OverridableTypeMap> = ((
  props: { href: string } & OverrideProps<ExtendButtonBaseTypeMap<TypeMap>, 'a'>,
) => React.JSX.Element) &
  OverridableComponent<ExtendButtonBaseTypeMap<TypeMap>>;

From what I can observe:

• When using Button directly, href and target work perfectly
• When wrapping Button in our custom component using ButtonProps, TypeScript doesn't recognize anchor attributes
• The component still works correctly at runtime anyway despite TypeScript errors when using ButtonProps

[ZeeshanTamboli]

When wrapping Button in our custom component using ButtonProps, TypeScript doesn't recognize anchor attributes

Is this a TypeScript limitation? And how? If so, we should document how to make it recognize the target attribute and mention that it's a TS limitation.

[Kartik-Murthy]

I spent some time looking into this, and while I couldn’t find anything concrete in the TypeScript documentation or issue tracker, it seems like TypeScript might be struggling with narrowing types when they’re passed through a generic wrapper.

It seems the Button component handles href and target fine because of how the overloads are set up in ExtendButtonBase. But when using ButtonProps in a wrapper, that conditional behavior seems to get flattened or lost, and target is no longer recognized.

I’m not sure if this is due to TypeScript limitations or just a side effect of how the types are structured. If anyone has more insight, I’d be happy to learn more or help clarify this further in the docs if it turns out to be expected behavior.

[ZeeshanTamboli]

I looked into it — this is a TypeScript limitation.

When you wrap Button in a custom component like CustomButton, TypeScript can't infer that target is valid when href is used.

As a workaround (though not ideal), you can explicitly extend both ButtonProps and anchor attributes:

import { Button, ButtonProps } from '@mui/material';

type AnchorButtonProps = ButtonProps & React.AnchorHTMLAttributes<HTMLAnchorElement>;

const CustomButton = (props: AnchorButtonProps) => {
  return <Button {...props} />;
};

export default function App() {
  return (
    <CustomButton href="https://example.com" target="_blank">
      My custom button
    </CustomButton>
  );
}

That said, if the custom component isn’t adding any new logic or props, I don't see much value in wrapping Button just to forward props — so I raised that question in the issue: #45729 (comment)

[ZeeshanTamboli]

Closing this PR since the related issue is a TS limitation. See #45765 (comment) and #45729 (comment)