Start Here

This page will have the basics that you'll want to start with when creating your chat app. Use the menu to jump to where you need to go.

Start Matrix

Password Login

const login = async () => {
  const result = await rnm.loginWithPassword(
    username,
    password,
    homeserver,
    true, // enable crypto? default false
  );
  if (result.error) {
    setLoading(false);
    console.log('Error logging in: ', result);
    setError(result.message);
  }
};

Token Login

rnm.createClient(homeserver, accessToken, mxid, deviceId?);
rnm.start(); // pass "true" to enable crypto

Get a list of rooms

Using Core

This is what's happening in /ui in the RoomList component behind the scenes. Render rooms and invites however you'd like. inviteList is a list of rooms you are not a part of yet, but have been invited to. updateLists is a function which refreshes the lists, usually in the event of an invite rejection / acceptance.

import { useMatrix, useRoomList } from '@rn-matrix/core'
...
// within your component
const { isReady, isSynced } = useMatrix();
const { roomList, inviteList, updateLists } = useRoomList();

if (!isReady || !isSynced) // return a loader 

return (
  <FlatList data={roomList} renderItem={...} />
)

Using UI

The RoomList component will show a simple inbox. However, you can override what it looks like by using the prop renderListItem. Read more at RoomList.

import { RoomList } from '@rn-matrix/ui'
...
function RoomListView() {
  const { isReady, isSynced } = useMatrix(); // you should still wait for these

  const onRowPress = (item) => {}
  
  if (!isReady || !isSynced) // return a loader 

  return <RoomList onRowPress={onRowPress} />
}

Join room

Be sure to update the lists after joinRoom resolves.

import rnm from '@rn-matrix/core'
...
const joinRoom = () => {
  rnm.getClient().joinRoom(room.roomId).then(updateLists)
}

Reject room invite

Be sure to update the lists after leaveRoom resolves.

import rnm from '@rn-matrix/core'
...
const rejectInvite = () => {
  rnm.getClient().leaveRoom(room.roomId).then(updateLists)
}

Get avatar for room

View the Room method getAvatarUrl

import rnm from '@rn-matrix/core'
...
const avatarSize = 50
const avatar = room.getAvatarUrl(
    rnm.getClient().getHomeserverUrl(),
    avatarSize,
    avatarSize,
    'crop',
    false
  )

Get messages in a room

Using Core

timeline is the actual list of messages.

updates is an array of messages that are deleted, edited, etc and therefore should be re-rendered in the view. Using this, you can memoize your MessageItem, reducing the number of useless re-renders on your screen.

To see an implementation of this including fetching previous messages, handling touches on the screen, rendering a typing indicator, etc, you can see that in the example app.

import { useTimeline } from '@rn-matrix/core'
...
export default function MessageView() {
  const { timeline, updates } = useTimeline(room);

  const renderMessageItem = ({item}) => <MessageItem message={message} />

  return (
    <FlatList
        inverted
        data={timeline}
        renderItem={renderMessageItem}
        keyExtractor={(item) => item.getId()}
      />
  )
}

Using UI

View the docs on MessageList to see what you can do for handling touches (onPress, onLongPress).

To see this in a code example, view this piece of the example app.

import { useTimeline } from '@rn-matrix/core'
...
export default function MessageView() {
  // Get "room" from navigation params, from clicking on it in the inbox 

  return <MessageList room={room} />
}

Send message to a room

Send message

Text

For automatic conversion of markdown to html:

rnm.sendTextMessage(roomId, content) // content is your markdown string

For basic sending (no alterations made):

rnm.getClient().sendTextMessage(roomId, content)

Image or Video

rnm.sendMediaMessage(roomId, content, type)

In this case, content is something that is received directly from something like ImagePicker.

type is either m.image or m.video

const openImagePicker = () => {
  const options = {
    mediaType: 'mixed',
  };
  ImagePicker.launchImageLibrary(options, async (response) => {
    if (response.didCancel) return;
    rnm.sendMediaMessage(response, response.type ? 'm.image' : 'm.video');
  });
};

Send reply

relatedMessage is the MatrixEvent which is being replied to.

rnm.sendReply(roomId, relatedMessage: MatrixEvent, messageText)

Edit message

import rnm from '@rn-matrix/core'
...
rnm.editMessage(roomId, messageId, newMessageContent: string)

Delete a message

import rnm from '@rn-matrix/core'
...
rnm.deleteMessage(MatrixEvent)

Create a room

Not available yet.