[material-ui][Typography] Deprecate `paragraph` prop

[walston]

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

Resolves #42382, resolves #16926

[mui-bot]

Netlify deploy preview

• docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

Bundle size report

No bundle size changes (Toolpad) No bundle size changes

Generated by :no_entry_sign: dangerJS against 78ffccaab2aea35dcb1c1f7b1cc9b46c6f713509

[walston]

thanks so much for the instructions @aarongarciah. Happy to make those changes later today.

[aarongarciah]

Hey @walston! Did you have a chance to take a look? We want to land this on v6, which should be out in the next few weeks.

[walston]

oh dang. I'd love that. Apologies, got caught up with a company onsite. I can spend some time working through these things next week. Top of my priorities list now!

[walston]

@aarongarciah As I update the migration doc, it looks like there's an expectation there will be a codemod to handle this... Am I expected to write that codemod?

[aarongarciah]

@walston in this case, I think a codemod doesn't make sense because there's no direct replacement for the paragraph behavior:

1. Renders as a <p> element.
2. Adds margin-bottom: 16px.

We could codemod number 1 with component="p", but we can't codemod number 2 because we can't possibly know what other styles are developers applying to the component instance and we might break their UIs. In this case, I think it makes sense to provide the instructions on how to migrate.

Even if it was possible, you could ask us to pick it up if you can't do it.

[arronhunt]

@aarongarciah I'm working with @walston to get this over the finish line :)

We could codemod number 1 with component="p", but we can't codemod number 2 because we can't possibly know what other styles are developers applying to the component instance and we might break their UIs. In this case, I think it makes sense to provide the instructions on how to migrate.

For 1: I don't think we event need to add the component prop, since <Typography> renders as a <p> by default. Unless a developer overrides this setting it would probably result in a lot of redundant code. Is there a way to check for this?

For 2: Would we want to suggest adding mb={2} for Typography elements that need margin? I'm still confused about MUI's preferences between mb and sx props for margins.

[aarongarciah]

Hey @arronhunt! Thanks for working on this.

From your comment I'm not sure if you're working on a codemod or not. Just in case, I think we shouldn't spend time in a codemod. Instead, we can focus on writing clear guidance on what changed in the Migrating from deprecated APIs page given we can't possibly know users' intent and where the styles are coming from.

---

For 1: I don't think we event need to add the component prop, since <Typography> renders as a

by default. Unless a developer overrides this setting it would probably result in a lot of redundant code. Is there a way to check for this?

The tag being rendered by Typography depends on the variant and some other props. Typography renders a <p> in these scenarios:

• variant="body1" (body1 is also used when no variant is passed)
• variant="body2"
• paragraph
• component="p" or component={MyCustomComponent} (that renders a <p>)
• variant="any_variant" paragraph
• variant="any_variant" component="p"

It's fine to omit component="p" if no variant is passed or if the variant is already rendering a <p> (body1 and body2). See this demo for more info https://mui.com/material-ui/react-typography/#usage.

For 2: Would we want to suggest adding mb={2} for Typography elements that need margin? I'm still confused about MUI's preferences between mb and sx props for margins.

We'll remove system props (e.g. mb={2}) so it's recommended to use the sx prop. See this RFC and this in-progress PR if you want to know more.

[aarongarciah]

Hey @arronhunt @walston! Let me know if you need any help.

[arronhunt]

@aarongarciah I just pushed updates to the docs, using sx props to set bottom margin for paragraphs. I agree that a codemod isn't necessary and we can rely on the upgrade instructions. Would love your feedback!

[aarongarciah]

Thank you so much, @walston and @arronhunt. I'll be making some last finishing touches before merging.

[aarongarciah]

@DiegoAndai I thought about the codemod, but I though it wouldn't be good because:

• marginBottom could be applied to an element from anywhere without the codemod noticing, and we could intefere with users's styles:
  • A custom class name
  • A global class name
  • Inline styles
  • A parent element applying styles to children
  • etc.
• Some people might don't want to use the sx prop.

Code wise it would look good but we could be breaking UIs by adding marginBottom ourselves. In that case, I think it's better to let users handle it. wdyt?

[DiegoAndai]

marginBottom could be applied to an element from anywhere without the codemod noticing, and we could intefere with users's styles:

Right, but if they were using the paragraph prop, they would expect this marginBottom to be applied to the element. So it should continue to work as they had it before the codemod.

Some people might don't want to use the sx prop.

That's fair. We could add the codemod and add the option to skip codemods in a follow-up PR if someone doesn't want to run it.

[aarongarciah]

Right, but if they were using the paragraph prop, they would expect this marginBottom to be applied to the element. So it should continue to work as they had it before the codemod.

Can we ensure the same specificity and the same source order so styles are applied just the same?

[aarongarciah]

@DiegoAndai tbh I'd love to know how many people rely on paragraph to know if it's worth spending time on the codemod 😅

[arronhunt]

So, I'm a designer and therefore not super familiar with codemods, but is there an existing pattern for providing them but make running them optional? I could see it being beneficial for those who have a lot of paragraph props and aren't using any specific margin styles. Otherwise, as a consumer of MUI, I like @DiegoAndai's idea of adding the comment to the migration instructions.

@\DiegoAndai tbh I'd love to know how many people rely on paragraph to know if it's worth spending time on the codemod 😅

@aarongarciah Anecdotally, our team has been relying on it for styling. It's actually what caused me to want to come here and fix the bad pattern lol.

[aarongarciah]

@arronhunt we'll probably provide a codemod, but if you want to contribute it you're more than welcome. Right now, we're focused on making Material UI compatible with React 19.

You can find codemod examples in the mui-codemod package. For example, the one for the Divider component, which removes the light prop and adds sx={{ opacity: 0.6 }} (docs).

[aarongarciah]

We could add the codemod and add the option to skip codemods in a follow-up PR if someone doesn't want to run it.

@DiegoAndai what did you have in mind for this? I'll be working on the codemod.

[aarongarciah]

Remove paragraph prop if found, and:

• Add sx={{ marginBottom: 2 }} if there's no sx prop
• Add marginBottom: 2 to sx if there's sx prop

@DiegoAndai this would only be 16px if they haven't modified the default theme spacing (8px by default)

[aarongarciah]

@DiegoAndai I just added a commit with the codemod. I went with 16px instead of 2 for the marginBottom value.

One doubt: should we cater for the mb shortcut being present in the object passed to sx?

[aarongarciah]

I need to update the migration guide.

[aarongarciah]

Ready for review.

[aarongarciah]

@DiegoAndai I just updated the codemod to cater for mb, too. Ready for a final review.

[aarongarciah]

Thanks @walston @arronhunt for working on this!