---
title: String.prototype.replaceAll()
slug: Web/JavaScript/Reference/Global_Objects/String/replaceAll
tags:
  - Expressão Regular
  - JavaScript
  - Prototipo
  - Referencia
  - String
  - metodo
  - regex
  - replaceAll()
translation_of: Web/JavaScript/Reference/Global_Objects/String/replaceAll
---
<div>{{JSRef}}</div>

<div class="blockIndicator note"><strong>Nota</strong>: A partir de Agosto de 2020, o método <code>replaceAll()</code> continuará sendo suportado pelo Firefox, mas não pelo Chrome. Ele estará disponível somente no Chrome 85.</div>

<p>O método <code>replaceAll()</code> retorna uma nova string com todas as ocorrências de um padrão substituídas por uma substituição. O padrão pode ser uma string ou uma {{jsxref ("RegExp")}}, e a substituição pode ser uma string ou uma função a ser chamada para cada ocorrência.<br>
 <br>
 A <em>string</em> original é mantida sem modificação.</p>

<div>{{EmbedInteractiveExample("pages/js/string-replaceall.html")}}</div>



<h2 id="Sintaxe">Sintaxe</h2>

<pre class="syntaxbox notranslate">const newStr = <var>str</var>.replaceAll(<var>regexp</var>|<var>substr</var>, <var>newSubstr</var>|<var>function</var>)
</pre>

<div class="blockIndicator note">
<p><strong>Nota</strong>: quando usar uma `<var>regexp</var>`, você deve colocar o sinalizador (flag) global "<code>g</code>". Do contrário, será retornado um <code>TypeError</code>: "<em>replaceAll must be called with a global RegExp</em>".</p>
</div>

<h3 id="Parâmetros">Parâmetros</h3>

<dl>
 <dt><code><var>regexp</var></code> (padrão)</dt>
 <dd>Uma {{jsxref ("RegExp")}} ou literal com o sinalizador (flag) global. As ocorrências serão substituídas por <em><code>newSubstr</code></em> ou pelo valor retornado da <em><code>function</code></em> (função) especificada.</dd>
 <dt><code><var>substr</var></code><var> </var>(padrão)</dt>
 <dd>Uma {{jsxref ("String")}} que deve ser substituída por <code>newSubstr</code>. É tratada como uma string literal e não é interpretada como uma expressão regular (<em><code>RegExp</code></em>).</dd>
 <dt><code><var>newSubstr</var></code> (substituição)</dt>
 <dd>É a {{jsxref("String")}} que substitui a <code><em>substring</em></code> especificada pelo parâmetro <code><var>regexp</var></code> ou <code><var>substr</var></code>. Um número de padrões especiais para substituição são suportados; veja a seção "<a href="#">Especificando uma string como parâmetro</a>" abaixo.</dd>
 <dt><code><var>function</var></code> (substituição)</dt>
 <dd>Uma função a ser chamada retornando a nova <code><em>substring</em></code> a ser usada para substituir as correspondências para a dada <code><var>regexp</var></code> ou <code><var>substr</var></code>. Os argumentos passados para esta função são descritos na seção "<a href="#Especificando uma função como parâmetro">Especificando uma função como parâmetro</a>" abaixo.</dd>
</dl>

<h3 id="Valor_de_retorno">Valor de retorno</h3>

<p>Um nova <em>string</em>, com todas as ocorrências de um padrão substituído por uma substituição.</p>

<h2 id="Descrição">Descrição</h2>

<p>Este método não muda o objeto {{jsxref("String")}} original. Ele simplesmente retorna uma nova <em>string</em>.</p>

<h3 id="Especificando_uma_string_como_parâmetro"><a id="Especificando uma string como parâmetro" name="Especificando uma string como parâmetro">Especificando uma string como parâmetro</a></h3>

<p>A <em>string</em> de substituição pode incluir os seguimentos padrões especiais de substituição:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th class="header" scope="col">Padrão</th>
   <th class="header" scope="col">Insere</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>$$</code></td>
   <td>Insere um <code>"$"</code>.</td>
  </tr>
  <tr>
   <td><code>$&amp;</code></td>
   <td>Insere a <em>substring</em> correspondente.</td>
  </tr>
  <tr>
   <td><code>$`</code></td>
   <td>Insere a porção da <em>string</em> que precede a <em>substring</em> correspondente.</td>
  </tr>
  <tr>
   <td><code>$'</code></td>
   <td>Insere a porção da <em>string</em> que sucede a <em>substring</em> correspondente.</td>
  </tr>
  <tr>
   <td><code>$<var>n</var></code></td>
   <td>Onde <code><var>n</var></code> é um inteiro positivo menor que 100, insere a <var><code>n</code></var>-ésima <em>string</em> submatch entre parênteses, desde que o primeiro argumento seja um objeto {{jsxref("RegExp")}}. Note que isso é indexado começando pelo <code>1</code>.</td>
  </tr>
 </tbody>
</table>

<h3 id="Especificando_uma_função_como_parâmetro"><a id="Especificando uma função como parâmetro" name="Especificando uma função como parâmetro">Especificando uma função como parâmetro</a></h3>

<p>Você pode especificar uma função como segundo parâmetro. Neste caso, a função será chamada depois da ocorrência ter sido encontrada. O resultado da função (valor de retorno) será usado como uma <em>string</em> para substituição. (<strong>Nota:</strong> Os padrões especiais mencionados acima <strong>não se aplicam </strong>neste caso.)</p>

<p>Note que a função será chamada múltiplas vezes para cada ocorrência a ser substituída se a expressão regular no primeiro parâmetro for global "<code>g</code>".</p>

<p>Os argumentos para funções são os seguintes:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th class="header" scope="col">Nome possível</th>
   <th class="header" scope="col">Valor fornecido</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>match</code></td>
   <td>A <em>substring</em> correspondida. (Corresponde ao <code>$&amp;</code> acima.)</td>
  </tr>
  <tr>
   <td><code>p1, p2, ...</code></td>
   <td>A <var>n</var>-ésima string encontrada por um grupo de captura entre parênteses, desde que o primeiro argumento para <code>replace()</code> seja uma {{jsxref("RegExp")}}. (Corresponde a <code>$1</code>, <code>$2</code>, etc. acima.) Por exemplo, se <code>/(\a+)(\b+)/</code>, foi dado, <code>p1</code> é a correspondência para <code>\a+</code>, e <code>p2</code> para <code>\b+</code>.</td>
  </tr>
  <tr>
   <td><code>offset</code></td>
   <td>O deslocamento da substring correspondente em toda a string sendo examinada. (Por exemplo, se toda a string for '<code>abcd</code>' e a substring correspondente for '<code>bc</code>', este argumento será <code>1</code>.)</td>
  </tr>
  <tr>
   <td><code>string</code></td>
   <td>A <em>string</em> inteira será examinada.</td>
  </tr>
 </tbody>
</table>

<p>(O número exato de argumentos depende se o primeiro argumento é um objeto {{jsxref("RegExp")}} — e, se então, quantas <em>subcorrespondências </em>entre parênteses são especificadas.)</p>

<h2 id="Exemplos">Exemplos</h2>

<h3 id="Usando_replaceAll">Usando <code>replaceAll()</code></h3>

<pre class="brush: js notranslate">'aabbcc'.replaceAll('b', '.');
// 'aa..cc'</pre>

<h3 id="RegExp_sem_flag_g_retorando_erro">RegExp sem flag "g" retorando erro</h3>

<p>Ao usar uma expressão regular para realizar uma pesquisa, a mesma deve conter a flag global "<code>g</code>". O código abaixo não irá funcionar:</p>

<pre class="brush: js; example-bad notranslate">'aabbcc'.replaceAll(/b/, '.');
TypeError: replaceAll must be called with a global RegExp
</pre>

<p>Já o código abaixo vai funcionar:</p>

<pre class="brush: js; example-good notranslate">'aabbcc'.replaceAll(/b/g, '.');
"aa..cc"
</pre>

<h2 id="Especificações">Especificações</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Especificação</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-string.prototype.replaceall', 'String.prototype.replaceAll')}}</td>
  </tr>
 </tbody>
</table>

<h2 id="Navegadores_compatíveis">Navegadores compatíveis</h2>

<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>

<p>{{Compat("javascript.builtins.String.replaceAll")}}</p>

<h2 id="Veja_também">Veja também</h2>

<ul>
 <li>{{jsxref("String.prototype.replace", "String.prototype.replace()")}}</li>
 <li>{{jsxref("String.prototype.match", "String.prototype.match()")}}</li>
 <li>{{jsxref("RegExp.prototype.exec", "RegExp.prototype.exec()")}}</li>
 <li>{{jsxref("RegExp.prototype.test", "RegExp.prototype.test()")}}</li>
</ul>