Gate a macro
If sheet.getRange('Settings!B1').getValue() !== 'ON', show an alert and return early so the tool does not run on production data.
What is getValue in Google Sheets Apps Script?
getValue reads the value from one cell in a Range object. It returns what you see in the grid as a string, number, date, or boolean. Scripts use getValue when they need one field at a time, such as a status flag, email address, or threshold from a Settings tab.
When to use it
Use getValue for single-cell reads: check if A1 is TRUE, read an API key cell, grab the active cell value in a custom menu, or branch on one dropdown before updating a row.
When to skip it
Skip getValue inside loops over many cells. Call getValues once on the range and loop the array instead. One getValue per cell is slow on large tables.
How it works
-
1
Get a Range with getRange('B2') or getActiveCell() on a sheet object.
-
2
Call range.getValue() to receive a single JavaScript value.
-
3
Dates often arrive as Date objects. Text stays a string even if the cell looks like a number.
-
4
Empty cells return an empty string in most cases, not null.
-
5
Compare carefully when the sheet stores numbers as text from imports.
-
6
Log typeof results while debugging unexpected branches.
Examples in Google Sheets
Read active cell
A custom menu action reads SpreadsheetApp.getActiveRange().getValue() and passes it to a search function.
Status check before email
getValue on column D of the current row returns Urgent before MailApp sends an alert.
Build this without starting from a blank cell
Use a Better Sheets tool for getValue, then watch a walkthrough when you want the full pattern.
Better Sheets resources
Common mistakes
- Calling getValue in a loop for ten thousand rows instead of one getValues call.
- Expecting display text when you need the raw value; use getDisplayValue for formatted strings.
- Not trimming string results that include stray spaces from IMPORTRANGE or paste.
- Comparing dates to strings without converting both sides consistently.
- Reading the wrong sheet because getActiveSheet changed while the user clicked around.
Frequently asked questions
- What is the difference between getValue and getDisplayValue?
- getValue returns the stored value. getDisplayValue returns what the cell shows, including currency symbols and date formatting.
- Does getValue return formulas?
- It returns the calculated result, not the formula text. Use getFormula for the formula string.
- What does an empty cell return?
- Usually an empty string. Test your branch logic for both blank and zero cases.
- Can getValue return an array?
- No. For multiple cells use getValues, which returns a 2D array even for one row or column.
- How do I read a checkbox cell?
- TRUE or FALSE as a boolean when the cell is a real checkbox. Typed TRUE as text is a string.
- Is getValue locale aware?
- Numbers are JavaScript numbers. Date parsing depends on how Sheets stored the value, not on the viewer locale string.
- Can I getValue from a protected range?
- Only if the account running the script can edit or unprotect that range, or protection allows the script owner.
- Why is my getValue undefined?
- You may be calling getValue on null if getRange failed, or on the wrong object type. Check the range reference first.
Related Tutorials
Watch how getValue works
Scrape Google Maps
Embed a Number in a Website from a Google Sheet
10 Google Sheets I Wish Someone Would Make
Calculate ROAS in Google Sheets
Extract URLs from Google Sheets
Saving OpenAI API Calls inside of Google Sheets
Related blog posts
Guides that explain getValue in more depth.
Extract URLs from Google Sheets
Extract url from hyperlink google sheets.Skip the Command K. This Google Sheet tutorial will make it easier for you to extract URLS from Google Sheets.
Read post →Explore Coding in Google Sheets
Did you know you can actually code in Google Sheets?
Read post →What's Better Than Google Sheets?
Nothing is better than Google Sheets. You just need to learn more about the unlimited power of Google Sheets. Functions, Formulas, Apps Script and more.
Read post →Related glossary terms
Script Editor
The Script Editor is the Apps Script workspace inside your spreadsheet where you write JavaScript that talks to Sheets, Gmail, and other Google services. You open it from Extensions > Apps Script. Every function you save can be run manually, bound to a trigger, or linked from a custom menu.
Read guide →Apps Script loops
Loops in Apps Script let you repeat code over rows, columns, sheets, or API pages. You read ranges into arrays with getValues(), process each item in a for or forEach loop, then write results back in one setValues() call when possible. Batch reads and writes beat cell-by-cell updates for speed and quota limits.
Read guide →Google Sheets automation
Automation means work happens without repeating the same clicks every day: imports update, emails send, rows move, and dashboards refresh. In Sheets, automation usually stacks built-in features, Apps Script, and sometimes the Sheets API or add-ons. Start with the lightest tool that still solves the job.
Read guide →Google Sheets workflows
A workflow is the path work takes through your sheet: intake, review, approval, done. Good workflows use consistent columns, statuses everyone understands, and just enough automation to move tasks forward without hiding steps from the team.
Read guide →Done reading about getValue?
Membership unlocks 636+ tutorials, unlimited generators, and every template. Practical lessons. Zero fluff.
Need this once
Jump to a free tool or a single tutorial for this topic.
Learning Sheets for real
Unlock the full library, generators, and templates with membership.