Skip to content

Commit

Permalink
Clean up README
Browse files Browse the repository at this point in the history
  • Loading branch information
@cooperka
cooperka committed Jul 10, 2017
1 parent 6029e94 commit 68b0609
Showing 1 changed file with 91 additions and 80 deletions.
171 changes: 91 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,51 @@
# Gifted Chat
The most complete chat UI for React Native (formerly known as Gifted Messenger)

The most complete chat UI for React Native (formerly known as Gifted Messenger).

![](https://raw.githubusercontent.com/FaridSafi/react-native-gifted-chat/master/screenshots/gifted-chat-1.png)
![](https://raw.githubusercontent.com/FaridSafi/react-native-gifted-chat/master/screenshots/gifted-chat-2.png)

## Features

- Fully customizable components
- Composer actions (to attach photos, etc.)
- Load earlier messages
- Copy messages to clipboard
- Touchable links using [react-native-parsed-text](https://github.com/taskrabbit/react-native-parsed-text)
- Avatar as user's initials
- Localized dates
- Multiline TextInput
- InputToolbar avoiding keyboard

## Dependency

- Use version `0.2.x` for RN `>= 0.44.0`
- Use version `0.1.x` for RN `>= 0.40.0`
- Use version `0.0.10` for RN `< 0.40.0`

## Installation
`npm install react-native-gifted-chat --save`

## Android installation
- Add `android:windowSoftInputMode="adjustResize"` to your Android Manifest `android/app/src/main/AndroidManifest.xml`
```xml
<!-- ... -->
<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:windowSoftInputMode="adjustResize"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
<!-- ... -->
```

- If you plan to use `GiftedChat` inside a `Modal`, see [#200](https://github.com/FaridSafi/react-native-gifted-chat/issues/200)

- Using [npm](https://www.npmjs.com/#getting-started): `npm install react-native-gifted-chat --save`
- Using [Yarn](https://yarnpkg.com/): `yarn add react-native-gifted-chat`

## Example

```jsx
import { GiftedChat } from 'react-native-gifted-chat';

class Example extends React.Component {
constructor(props) {
super(props);
this.state = {messages: []};
this.onSend = this.onSend.bind(this);
}

state = {
messages: [],
};

componentWillMount() {
this.setState({
messages: [
{
_id: 1,
text: 'Hello developer',
createdAt: new Date(Date.UTC(2016, 7, 30, 17, 20, 0)),
createdAt: new Date(),
user: {
_id: 2,
name: 'React Native',
Expand All @@ -54,32 +55,37 @@ class Example extends React.Component {
],
});
}

onSend(messages = []) {
this.setState((previousState) => {
return {
messages: GiftedChat.append(previousState.messages, messages),
};
});
this.setState((previousState) => ({
messages: GiftedChat.append(previousState.messages, messages),
}));
}

render() {
return (
<GiftedChat
messages={this.state.messages}
onSend={this.onSend}
onSend={(messages) => this.onSend(messages)}
user={{
_id: 1,
}}
/>
);
}

}
```

## Advanced example
See [example/App.js](example/App.js)

See [example/App.js](example/App.js) for a working demo!

## Message object
```javascript

e.g.

```js
{
_id: 1,
text: 'My message',
Expand All @@ -90,63 +96,68 @@ See [example/App.js](example/App.js)
avatar: 'https://facebook.github.io/react/img/logo_og.png',
},
image: 'https://facebook.github.io/react/img/logo_og.png',
// additional custom parameters
// Any additional custom parameters are passed through
}
```

## Props

- **`messages`** _(Array)_ - messages to display
- **`messageIdGenerator`** _(Function)_ - generate id for new message. By default is a UUID v4 generated by [uuid](https://github.com/kelektiv/node-uuid).
- **`user`** _(Object)_ - user sending the messages `{_id, name, avatar}`
- **`onSend`** _(Function)_ - function to call when sending a message
- **`locale`** _(String)_ - localize the dates
- **`isAnimated`** _(Bool)_ - animates the view when the keyboard appears
- **`loadEarlier`** _(Bool)_ - enables the load earlier message button
- **`onLoadEarlier`** _(Function)_ - function to call when loading earlier messages
- **`isLoadingEarlier`** _(Bool)_ - display an ActivityIndicator when loading earlier messages
- **`renderLoading`** _(Function)_ - render a loading view when initializing
- **`renderLoadEarlier`** _(Function)_ - render the load earlier button
- **`renderAvatar`** _(Function)_ - renders the message avatar. Set to `null` to not render any avatar for the message
- **`onPressAvatar`** _(Function(`user`))_ - callback when a message avatar is tapped
- **`renderAvatarOnTop`** _(Bool)_ - render the message avatar, on top of consecutive messages. The default value is `false`.
- **`renderBubble`** _(Function)_ - render the message bubble
- **`onLongPress`** _(Function(`context`, `message`))_ - callback when a message bubble is long-pressed (default is to show action sheet with "Copy Text"). See code for example using `context.actionSheet().showActionSheetWithOptions()`.
- **`renderMessage`** _(Function)_ - render the message container
- **`renderMessageText`** _(Function)_ - render the message text
- **`renderMessageImage`** _(Function)_ - render the message image
- **`imageProps`** _(Object)_ - extra props to be passed to the [`<Image>`](https://facebook.github.io/react-native/docs/image.html) component created by the default `renderMessageImage`
- **`lightboxProps`** _(Object)_ - extra props to be passed to the MessageImage's [Lightbox](https://github.com/oblador/react-native-lightbox)
- **`renderCustomView`** _(Function)_ - render a custom view inside the bubble
- **`renderDay`** _(Function)_ - render the day above a message
- **`renderTime`** _(Function)_ - render the message time
- **`renderFooter`** _(Function)_ - renders a fixed bottom view. Can be used for 'is typing message', see [example/App.js](example/App.js)
- **`renderInputToolbar`** _(Function)_ - render the composer container
- **`renderActions`** _(Function)_ - renders an action button on the left of the message composer
- **`renderComposer`** _(Function)_ - render the text input message composer
- **`renderSend`** _(Function)_ - render the send button
- **`renderAccessory`** _(Function)_ - renders a second line of actions below the message composer
- **`onPressActionButton`** _(Function)_ - callback to perform custom logic when the Action button is pressed (the default `actionSheet` will not be used)
- **`bottomOffset`** _(Integer)_ - distance of the chat from the bottom of the screen, useful if you display a tab bar
- **`minInputToolbarHeight`** _(Integer)_ - minimum height of the input toolbar. The default value is `44`.
- **`listViewProps`** _(Object)_ - extra props to be passed to the [`<ListView>`](https://facebook.github.io/react-native/docs/listview.html), some props can not be override, see the code in `render` method of `MessageContainer` for detail
- **`keyboardShouldPersistTaps`** _(Enum)_ - determines when the keyboard should stay visible after a tap [`<ScrollView>`](https://facebook.github.io/react-native/docs/scrollview.html)
- **`onInputTextChanged`** _(Function)_ - function that will be called when input text changes
- **`maxInputLength`** _(Integer)_ - max Composer TextInput length

## Features
- Custom components
- InputToolbar avoiding keyboard
- Multiline TextInput
- Load earlier messages
- Avatar as initials
- Touchable links using [react-native-parsed-text](https://github.com/taskrabbit/react-native-parsed-text)
- Localized dates
- Copy text messages to clipboard

- **`messages`** _(Array)_ - Messages to display
- **`messageIdGenerator`** _(Function)_ - Generate an id for new messages. Defaults to UUID v4, generated by [uuid](https://github.com/kelektiv/node-uuid)
- **`user`** _(Object)_ - User sending the messages: `{ _id, name, avatar }`
- **`onSend`** _(Function)_ - Callback when sending a message
- **`locale`** _(String)_ - Locale to localize the dates
- **`isAnimated`** _(Bool)_ - Animates the view when the keyboard appears
- **`loadEarlier`** _(Bool)_ - Enables the "Load earlier messages" button
- **`onLoadEarlier`** _(Function)_ - Callback when loading earlier messages
- **`isLoadingEarlier`** _(Bool)_ - Display an `ActivityIndicator` when loading earlier messages
- **`renderLoading`** _(Function)_ - Render a loading view when initializing
- **`renderLoadEarlier`** _(Function)_ - Custom "Load earlier messages" button
- **`renderAvatar`** _(Function)_ - Custom message avatar; set to `null` to not render any avatar for the message
- **`onPressAvatar`** _(Function(`user`))_ - Callback when a message avatar is tapped
- **`renderAvatarOnTop`** _(Bool)_ - Render the message avatar at the top of consecutive messages, rather than the bottom (default)
- **`renderBubble`** _(Function)_ - Custom message bubble
- **`onLongPress`** _(Function(`context`, `message`))_ - Callback when a message bubble is long-pressed; default is to show an ActionSheet with "Copy Text" (see [example using `showActionSheetWithOptions()`](https://github.com/FaridSafi/react-native-gifted-chat/blob/master/example/CustomActions.js))
- **`renderMessage`** _(Function)_ - Custom message container
- **`renderMessageText`** _(Function)_ - Custom message text
- **`renderMessageImage`** _(Function)_ - Custom message image
- **`imageProps`** _(Object)_ - Extra props to be passed to the [`<Image>`](https://facebook.github.io/react-native/docs/image.html) component created by the default `renderMessageImage`
- **`lightboxProps`** _(Object)_ - Extra props to be passed to the `MessageImage`'s [Lightbox](https://github.com/oblador/react-native-lightbox)
- **`renderCustomView`** _(Function)_ - Custom view inside the bubble
- **`renderDay`** _(Function)_ - Custom day above a message
- **`renderTime`** _(Function)_ - Custom time inside a message
- **`renderFooter`** _(Function)_ - Custom fixed bottom view, e.g. "User is typing..."; see [example/App.js](example/App.js) for an example
- **`renderInputToolbar`** _(Function)_ - Custom message composer container
- **`renderComposer`** _(Function)_ - Custom text input message composer
- **`renderActions`** _(Function)_ - Custom action button on the left of the message composer
- **`renderSend`** _(Function)_ - Custom send button
- **`renderAccessory`** _(Function)_ - Custom second line of actions below the message composer
- **`onPressActionButton`** _(Function)_ - Callback when the Action button is pressed (if set, the default `actionSheet` will not be used)
- **`bottomOffset`** _(Integer)_ - Distance of the chat from the bottom of the screen (e.g. useful if you display a tab bar)
- **`minInputToolbarHeight`** _(Integer)_ - Minimum height of the input toolbar; default is `44`
- **`listViewProps`** _(Object)_ - Extra props to be passed to the messages [`<ListView>`](https://facebook.github.io/react-native/docs/listview.html); some props can't be overridden, see the code in `MessageContainer.render()` for details
- **`keyboardShouldPersistTaps`** _(Enum)_ - Determines whether the keyboard should stay visible after a tap; see [`<ScrollView>`](https://facebook.github.io/react-native/docs/scrollview.html) docs
- **`onInputTextChanged`** _(Function)_ - Callback when the input text changes
- **`maxInputLength`** _(Integer)_ - Max message composer TextInput length

## Notes for Android

- Make sure you have `android:windowSoftInputMode="adjustResize"` in your `AndroidManifest.xml`:

```xml
<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:windowSoftInputMode="adjustResize"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
```

- If you plan to use `GiftedChat` inside a `Modal`, see [#200](https://github.com/FaridSafi/react-native-gifted-chat/issues/200).

## License

- [MIT](LICENSE)

## Author

Feel free to ask me questions on Twitter [@FaridSafi](https://www.twitter.com/FaridSafi) !
Feel free to ask me questions on Twitter [@FaridSafi](https://www.twitter.com/FaridSafi)!

0 comments on commit 68b0609

Please sign in to comment.