Replace first occurrence
In “one two one three one”, replacing the first “one” with “FIRST” gives “FIRST two one three one”, and the later matches stay exactly as they were. The search is literal, with an optional mode that ignores capital letters. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Text
- one two one three one
- Find
- one
- Replace
- FIRST
- Result
- FIRST two one three one
- Text
- FIRST two one three one
- Original
- one two one three one
- Quantity
- 1
Editors, engineers, and automation pipelines often need a precise edit: change only the first mention of a word or token and leave every later occurrence alone. Global find-and-replace rewrites the whole document and can break examples, logs, or repeated product names you still need. An optional case-insensitive flag covers mixed-case drafts where the first Hello or HELLO should change without scanning every later form. Empty search terms fail with invalid input so bulk jobs never run a silent no-op.
What replace first occurrence means and when to use it
Replace first occurrence means scan the source string from the left, stop at the first non-overlapping match of a search term, write a replacement string in that single place, and leave every later match untouched—including when the replacement is empty so you only delete the first hit. Matching is literal: if you search for a period or a parenthesis, those characters are plain text, not regular-expression syntax, so the tool stays predictable for non-developers and for pipelines that must never surprise on special characters.
Prefer this calculator when the search intent is replace first occurrence, swap only the first match, edit the first substring, or change the first token without a global rename. Optional case-insensitive matching folds letter case so the first Hello, HELLO, or hello is caught without listing variants. Do not use this product when you need every match replaced—that is a different SEO intent served by find-and-replace-all tools—or when you need capture groups, lookarounds, or multi-line regex engines.
What you can do with it
First brand or product name only
Update the opening product name in marketing copy while leaving later example names, SKUs, and demo strings unchanged.
Leading token cleanup in templates
Delete or rewrite only the first placeholder token or legacy prefix in macros, email snippets, and config lines.
FAQ
How do I replace only the first occurrence of a substring?
Optional replace is the substitution (defaults to empty, which deletes the first match). The response includes result, count, and index.
What happens if the search term is empty?
An empty find string is rejected so pipelines never run a silent no-op or the classic empty-string replace footgun; those failures are not charged.
How is this different from find and replace all?
This tool changes only the first match and leaves later matches untouched. Find-and-replace-all swaps every occurrence. Use replace-first when you need a precise single edit.
Is the replace first occurrence tool free?
The browser tool runs free on your device.
Does find support regular expressions?
No. The search term is always treated as a literal string. Periods, brackets, and other regex metacharacters match themselves so the behavior stays predictable for editors and bulk jobs.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/str/replace-first \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"one two one three one","find":"one"}'const res = await fetch("https://api.kit.forhosting.com/str/replace-first", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "one two one three one",
"find": "one"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/str/replace-first",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"text": "one two one three one",
"find": "one"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/str/replace-first", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"text":"one two one three one","find":"one"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"text":"one two one three one","find":"one"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/str/replace-first", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"text": "one two one three one",
"find": "one"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "str.replace_first",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
What replace first occurrence means and when to use it
Typical sources include document titles where only the opening product name should update, log lines where the first error code is rewritten for demos, CSV cells with a leading legacy prefix, and notes where a misspelling appears once at the top and correctly later. An empty search term raises invalid_input, which protects bulk jobs from the classic footgun of treating the empty string as a match between every character.
Input contract, empty search rejection, and reading the response
Optional replace defaults to the empty string, which deletes only the first match. Use result alone when you only need the cleaned string; use count and index when a pipeline logs whether and where the edit landed; use original and result together when a demo UI must show before-and-after. Source text follows the same retention rules as other KIT parse items. Send a JSON body with the required string field text set to the source you want edited and the required string field find set to a non-empty search term. Optional case_insensitive defaults to false for exact case; set it true when the first mixed-case draft should still match. Aliases are accepted for older clients: text also as input, value, s, content, or source; find as search, needle, from, or old; replace as replacement, with, to, or new; case_insensitive as ignore_case, ci, or insensitive. Missing text, missing find, a non-string value, or an empty find string all raise invalid_input with a message that names the problem, and those failures are not charged on the prepaid API. Keep payloads to ordinary phrase, paragraph, and short document sizes suitable for a Worker isolate rather than multi-megabyte dumps.
API usage, pricing, workflows, and practical limits
Call the free in-browser replace first occurrence tool for paste cleanup, classroom demos, content QA, and quick single-hit renames without installing a desktop utility or writing indexOf-and-slice snippets in every language. A typical workflow renames only the first brand mention in a product blurb so later example names stay intact, then checks count equals one and index points at the expected offset. Do not expect HTML-aware rewriting that skips tags, structured document merge fields, or locale-specific collation beyond standard ignore-case matching—those are separate problems. Authors shipping SDKs can document text and find as required fields and show a multi-match source where only the first hit changes plus an empty-find error example so integrators see both sides of the contract. Use the prepaid KIT API when a CMS, ETL job, form backend, support desk, or mobile client needs the same transform under balance at $0.002 per successful item; validation failures never consume balance after the engine rejects the request. Another workflow deletes a leading deprecated token by sending an empty replace, or normalizes the first mixed-case variant with case_insensitive true before search indexing. Pair this endpoint with full find-and-replace when a later step truly needs every match, but keep replace-first as its own landing so the SEO intent is not mixed with replace-all tools.
Integration use cases
QA and deterministic fixtures
Test harnesses pin replace-first golden outputs so refactors that switch to replace-all or change empty-find rejection fail continuous integration immediately.