MSC4427: Custom banners for user profiles by cyrneko · Pull Request #4427 · matrix-org/matrix-spec-proposals

cyrneko · 2026-02-25T22:49:08Z

Signed-off-by: Alexia cyrus42@disroot.org

turt2live · 2026-02-25T22:51:51Z

Implementation requirements:

Client (sending)

Client (rendering)

Question, for an implementation to be valid...can it be one that is compatible but uses a different field?

I've just found out that Commet apparently implements this, with the same semantics, however uses chat.commet.profile_banner instead of eu.cyrneko.msc4427.banner / m.banner

I assume not, but I thought I'd ask just in case

I've pushed a commit that makes the unstable prefix chat.commet.profile_banner

This means there is now two known implementations for this feature:

https://github.com/commetchat/commet

https://github.com/7w1/sable

respective commits:

Commet: commetchat/commet@95b69ff

Sable: 7w1/sable@e4f5087

Both of these can set a banner as well as display it on profiles.

Question, for an implementation to be valid...can it be one that is compatible but uses a different field?

Sure, as long as the spec your describing in this MSC matches an implementation it's valid. The reason for this check is to ensure that the proposal works and the field names do not need to align for that.

And there is precedence for using a existing field name as a unstable key 👍

Client (Haven Desktop): Haven-Organization/haven-desktop@d6269d4

Client implementation (Voyage):

VoyageClient/Voyage@15b4729

from `eu.cyrneko.msc4427.banner_url` to `chat.commet.profile_banner`

Johennes · 2026-03-02T07:24:04Z

+
+Clients can then use this field to load user banners.
+
+## Potential issues


Would we benefit from a recommendation for the banner dimensions or is this something you'd expect to work itself out organically across clients and users?

I think this will probably end up being an implementation detail, though I feel guidelines around aspect ratio would make sense probably? Something along the lines of perhaps 1:√2¹ or another aspect ratio

Footnotes

okay, I admit, that's me being a nerd for DIN standard paper sizes. There isn't really necessarily a reason I suggest this ratio in particular ↩

Maybe worth comparing with other platforms. From a quick check:

Mastodon uses 1500x500 pixels (3:1)

Discord uses 680x240 pixels (2.8:1)

LinkedIn uses 4200x700 pixels (6:1)

I can see the point on both to be honest. Mandating an aspect ratio is almost certainly going to be impossible, as clients require their own agency about how to display the banner.

That said, perhaps some wording that banners should be landscale an approximately 3:1 (clients MAY use techniques such as letterboxing or scaling if a banner doesn't fit)

that sounds good! I'll add that to the doc

if I don't forget at least...

I did, indeed, forget!

I'll set a reminder with a link to this...

1vel · 2026-03-26T12:47:32Z

(psst, you made the rendered link point to the first revision only)

1vel · 2026-03-26T13:06:03Z

+  "displayname": "Alice Margatroid",
+  "m.example_field": "custom_value",
+  "m.tz": "Europe/London",
+  "m.banner_url": "mxc://matrix.org/example123"


Perhaps it should be m.banner_uri instead, given this is a new field and it doesn't accept URLs (seemingly). Maybe it should also be noted that this must be an MXC URI.

that checks out, actually; it wasn't intended that non-mxc-URIs are to be used here and I just wrote url from muscle-memory, I'll fix that in a little bit

"url" is currently the standard in other places we have mxc's, e.g. avatar_url

hm, that is true...but perhaps this should be changed for new fields...? either way I intend MXC URIs so I'll probably clarify that and push. (finally coming back to this)

avatar_url does not support arbitrary URLs either, it mandates MXC URIs, yet it is labeled avatar_url

I believe url in places that only accept MXC URIs is due to the fields previously accepting URLs, however I haven't verified this. Correction appreciated.

@velikopter no thats not the case

The sauce gets saucier. The spec doesn't mandate avatar_url being an MXC URI in all places.

For example:

https://spec.matrix.org/v1.19/client-server-api/#mroommember

https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidjoined_members

The sauce gets saucier. The spec doesn't mandate avatar_url being an MXC URI in all places.

For example:

1. ![](https://private-user-images.githubusercontent.com/232914828/623842680-cf89bbff-9889-48ca-81a7-b832a45d4d4e.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODQ1NTM4ODIsIm5iZiI6MTc4NDU1MzU4MiwicGF0aCI6Ii8yMzI5MTQ4MjgvNjIzODQyNjgwLWNmODliYmZmLTk4ODktNDhjYS04MWE3LWI4MzJhNDVkNGQ0ZS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNzIwJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDcyMFQxMzE5NDJaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT00YmMyYjQ2ZDI5NmZkMWY2MjUwN2JhMmJhYjZlODJkMTBiODc3ZTlhMTQ0MTAzNzcxOGI2ZGJhYTAxYTZhY2FhJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.nNwGoQLggT2-uUgCk2oBA4snP3UDTWhycsyHDEAJ3AE) https://spec.matrix.org/v1.19/client-server-api/#mroommember 2. ![](https://private-user-images.githubusercontent.com/232914828/623842889-83ba8d15-e8ac-4ec6-80ea-1ebacd13c8e4.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODQ1NTM4ODIsIm5iZiI6MTc4NDU1MzU4MiwicGF0aCI6Ii8yMzI5MTQ4MjgvNjIzODQyODg5LTgzYmE4ZDE1LWU4YWMtNGVjNi04MGVhLTFlYmFjZDEzYzhlNC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNzIwJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDcyMFQxMzE5NDJaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT0yNjRmMjJhNzU3YTUyOGIyNmMwYWNhMGMxNWFhMjc5ZjcwNTYzYTE2ODk5ZWY0Mzc3MGQ1ZDJiYjM0Y2VjOTRkJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZyZXNwb25zZS1jb250ZW50LXR5cGU9aW1hZ2UlMkZwbmcifQ.79ahy1VZCkh2Fzyt9PC39V2ndEIo3B-ixsKTM5NX8jM) https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidjoined_members

This is a documentation issue, for privacy reasons non-MXC URLs must NOT be fetched by client. You can refer to matrix client implementations for that

I'll leave it as URL and keep the warning for implementers to only load MXC:// URIs in

cyrneko · 2026-03-28T16:45:17Z

(psst, you made the rendered link point to the first revision only)

oops, totally missed that, but it's fixed now, ty!

catfromplan9 · 2026-07-18T22:26:32Z

@cyrneko consider reverting url -> uri, url matches similar syntax elsewhere, namely avatar_url on rooms and memberships. I think that even if uri is pedantically correct it would be better to adhere to pre-established stylistic choices that exist in the spec

I had initially done this to try and be "correct", but perhaps changing existing norms in the spec is outside the scope of this MSC, and I should just stick to existing norms.

cyrneko · 2026-07-19T00:34:35Z

@catfromplan9 done.

cyrneko · 2026-07-20T19:46:12Z

smh the spellcheck still thinks commet is wrong

catfromplan9 · 2026-07-21T18:56:50Z

Is this also supported per-room (as in, on join events)?

cyrneko · 2026-07-22T00:15:07Z

Is this also supported per-room (as in, on join events)?

Not through join events, only maybe through things such as MSC4144, but that is out-of-scope for this MSC.

catfromplan9 · 2026-07-22T20:20:57Z

Is this also supported per-room (as in, on join events)?

Not through join events, only maybe through things such as MSC4144, but that is out-of-scope for this MSC.

Why not m.room.member state events? Its very straightforward to support

catfromplan9 · 2026-07-22T20:22:19Z

I implemented the m.room.member state event support for banners in my client, would like if it were in this MSC

catfromplan9 · 2026-07-22T22:19:10Z

Should also be kept in mind that profile lookup over federation may be disabled. If this is the case, then the only way a banner could be visible is to support it on m.room.member state events. Since the membership state event is per-room, this requires this MSC to also support propagating a global banner change server-side into all rooms the user is a member of when it is changed, as is already done for display name and avatar changes.

cyrneko · 2026-07-23T17:32:12Z

hm, I'm not sure if this MSC should be the one to introduce that, I did initially just want to standardize existing behavior based on extended profile data, m.room.member state events are a different mechanism altogether with different considerations¹, and I don't know many clients that implement this behavior in m.room.member events as opposed to using extended profile data. I think Extera might still be doing that, but they don't follow this MSC to begin with.

I am also not aware of the specifics of that mechanism so I'd have to read the spec for that part first, but that's the lesser of my worries

My primary concern is that they're another reason state-events are sent to potentially hundreds or thousands of rooms, in addition to name and avatar. I was never really a huge fan of that as it means more waiting time for changes to propagate, as opposed to the basically-instant nature of extended profile data and PMPs, which also discourages changing this data often (which is something I know some like to do). ↩

catfromplan9 · 2026-07-24T00:48:27Z

hm, I'm not sure if this MSC should be the one to introduce that, I did initially just want to standardize existing behavior based on extended profile data, m.room.member state events are a different mechanism altogether with different considerations1, and I don't know many clients that implement this behavior in m.room.member events as opposed to using extended profile data. I think Extera might still be doing that, but they don't follow this MSC to begin with.

I am also not aware of the specifics of that mechanism so I'd have to read the spec for that part first, but that's the lesser of my worries

Footnotes
1. My primary concern is that they're _another_ reason state-events are sent to potentially hundreds or thousands of rooms, in addition to name and avatar. I was never really a huge fan of that as it means more waiting time for changes to propagate, as opposed to the basically-instant nature of extended profile data and PMPs, which also discourages changing this data often (which is something I know some like to do). [↩](#user-content-fnref-1-63d25e82ccf041064ede23fd5d833ebe)

Well what I mean is, if profile lookups are disabled on the homeserver then you rely on member state events. You could leave propagation of the state event up to the client (meaning no server side change is necessary) so all you'd have to do is add a section about them being defined first by per-room m.room.member state events

This lets you have per-room banners supported, and if you want then you don't need to propagate it into all the rooms when changed on your client (if you assume your userbase is on servers with profile lookup enabled)

matrix-org#4427 (comment) Co-authored-by: Tulir Asokan <tulir@maunium.net>

cyrneko added 2 commits February 25, 2026 23:47

MSC0000: Custom banners for user profiles

0898436

MSC0000 → MSC4427

508041c

cyrneko changed the title ~~MSC0000: Custom banners for user profiles~~ MSC4427: Custom banners for user profiles Feb 25, 2026

turt2live reviewed Feb 25, 2026

View reviewed changes

tulir reviewed Feb 25, 2026

View reviewed changes

Comment thread proposals/4427-user-banners.md Outdated

tulir reviewed Feb 25, 2026

View reviewed changes

Comment thread proposals/4427-user-banners.md Outdated

banner_url > m.banner_url / eu.cyrneko.msc4427.banner_url

88db72b

Gnuxie mentioned this pull request Feb 26, 2026

MSC4426: User Status Profile Fields #4426

Open

change prefix

992c686

from `eu.cyrneko.msc4427.banner_url` to `chat.commet.profile_banner`

Johennes reviewed Mar 2, 2026

View reviewed changes

add note about aspect ratios

c961a06

smokku referenced this pull request in smokku/cinny Mar 23, 2026

Port extended user profile, nicknames and presence handling from Sable

4c41946

1vel reviewed Mar 26, 2026

View reviewed changes

cyrneko added 2 commits July 18, 2026 23:40

switch url → uri

383367c

Clarify that m.banner_uri should have MXC URIs exclusively

a93e641

revert to banner_url on request of commenters

0ff7a32

I had initially done this to try and be "correct", but perhaps changing existing norms in the spec is outside the scope of this MSC, and I should just stick to existing norms.

tulir reviewed Aug 8, 2026

View reviewed changes

Comment thread proposals/4427-user-banners.md Outdated

Apply changes based on Feedback

395c0d9

matrix-org#4427 (comment) Co-authored-by: Tulir Asokan <tulir@maunium.net>


		Clients can then use this field to load user banners.

		## Potential issues

Uh oh!

Conversation

cyrneko commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

if I don't forget at least...

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1vel commented Mar 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

catfromplan9 Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cyrneko commented Mar 28, 2026

Uh oh!

catfromplan9 commented Jul 18, 2026

Uh oh!

cyrneko commented Jul 19, 2026

Uh oh!

cyrneko commented Jul 20, 2026

Uh oh!

catfromplan9 commented Jul 21, 2026

Uh oh!

cyrneko commented Jul 22, 2026

Uh oh!

catfromplan9 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

catfromplan9 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

catfromplan9 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cyrneko commented Jul 23, 2026

Footnotes

cyrneko commented Feb 25, 2026 •

edited

Loading

catfromplan9 Jul 20, 2026 •

edited

Loading

catfromplan9 commented Jul 22, 2026 •

edited

Loading

catfromplan9 commented Jul 22, 2026 •

edited

Loading

catfromplan9 commented Jul 22, 2026 •

edited

Loading

catfromplan9 commented Jul 24, 2026 •

edited

Loading