useMessage() function

A custom React hook providing an entry from the messages object of the current or given locale. The returned value will be undefined if not found.

If the identified message value is a function, the returned value will be the result of calling it with a single argument params, or {} if empty. Otherwise the value set in the MessageProvider props will be returned directly.


export declare function useMessage(id: string | string[], params?: unknown, locale?: string | string[]): any;


Parameter Type Description
id string | string[] The key or key path of the message or message object. If empty or [], matches the root of the messages object
params unknown (Optional) Argument to use if the identified message is a function
locale string | string[] (Optional) If set, overrides the current locale precedence as set by parent MessageProviders.




import React from 'react'
import { MessageProvider, useLocales, useMessage } from '@messageformat/react'

const en = { example: { key: 'Your message here' } }
const fi = { example: { key: 'Lisää viestisi tähän' } }

// Intl.ListFormat may require a polyfill, such as intl-list-format
function Example() {
  const locales = useLocales() // ['fi', 'en']
  const lfOpt = { style: 'long', type: 'conjunction' }
  const lf = new Intl.ListFormat(locales, lfOpt)
  const lcMsg = lf.format( => JSON.stringify(lc))) // '"fi" ja "en"'
  const keyMsg = useMessage('example.key') // 'Lisää viestisi tähän'
  return (

export const App = () => (
  <MessageProvider locale="en" messages={en}>
    <MessageProvider locale="fi" messages={fi}>
      <Example />