OptionValue[name]
gives the value of name in options matched by OptionsPattern.
OptionValue[f,name]
gives the value of name for options associated with the head f.
OptionValue[f,opts,name]
extracts option values from the explicit list of rules opts.
OptionValue[…,{name1,name2,…}]
extracts several option values.
OptionValue
OptionValue[name]
gives the value of name in options matched by OptionsPattern.
OptionValue[f,name]
gives the value of name for options associated with the head f.
OptionValue[f,opts,name]
extracts option values from the explicit list of rules opts.
OptionValue[…,{name1,name2,…}]
extracts several option values.
Details
- OptionValue[name] is equivalent to OptionValue[f,name], where f is the head of the left-hand side of the transformation rule in which OptionValue[name] appears.
- OptionValue[f,name] and OptionValue[name] will use values from the first OptionsPattern object that appears as an argument of f.
- In OptionValue[f,opts,name], only the explicit list opts and the defaults derived from f will be considered.
- In OptionValue[f,opts,name], f can be a symbol, a rule, or a list of symbols and rules specifying default values. Each symbol s in f is equivalent to Options[s]. If the same option name is specified multiple times, the first specification determines the default.
- OptionValue[f,opts,name,Hold] returns the option value with Hold wrapped around it.
- OptionValue[Automatic,Automatic,name,Hold] is equivalent to OptionValue[name], except that the option value is returned with Hold wrapped around it.
- OptionValue ignores contexts when comparing option names and treats the symbol s and the string SymbolName[s] interchangeably.
Examples
open all close allBasic Examples (1)
Define default option values for the function f:
Options[f] = {a -> a0, b -> b0};Define f, allowing options to be given:
f[x_, OptionsPattern[]] := {x, OptionValue[a]}Use f with an explicit option setting:
f[7, a -> uuu]Use f with options taken to have their default values:
f[7]Scope (4)
Retrieve several option values at once:
OptionValue[Plot, {Frame, PlotPoints}]Use an explicit list of options:
OptionValue[Plot, {PlotRange -> Full}, {PlotRange, PlotRangePadding}]Define a transformation rule using multiple OptionsPattern constructs:
Options[f] = {a -> 1};
Options[g] = {a -> 2};
f[g[OptionsPattern[]], OptionsPattern[]] := {OptionValue[a], OptionValue[f, a], OptionValue[g, a]}OptionValue[a] is treated as OptionValue[f,a] because it is the outer head:
f[g[]]OptionValue tracks where a particular option was specified:
f[g[a -> 3], a -> 4]Use Hold in the fourth argument to return the unevaluated forms of options using RuleDelayed:
OptionValue[{Assumptions :> $Assumptions}, {}, Assumptions, Hold]Without the Hold, the current value of $Assumptions would be returned:
OptionValue[{Assumptions :> $Assumptions}, {}, Assumptions]Applications (2)
Define the default option values for a function f:
Options[f] = {"Square" -> False}Implement f using a helper function fCore, but still inherit defaults from f:
f[args___] := fCore[f, args]
fCore[f, x_, OptionsPattern[f]] := If[OptionValue["Square"], x ^ 2, x, "BadOptionValue"]The default option value of f is honored:
f[2]An explicit option setting takes precedence:
f[2, "Square" -> True]Define two functions with options:
Options[f] = {a -> 1, b -> 2};
Options[g] = {b -> 3, c -> 4};Define a function h that uses both sets of options, giving preference to the defaults of g:
h[opts : OptionsPattern[]] := OptionValue[{g, f}, {opts}, {a, b, c}]h[]h[a -> 10, b -> 7]Properties & Relations (4)
Contexts are ignored when comparing option names:
OptionValue[{foo`a -> 1}, bar`a]A string and a symbol are treated interchangeably:
OptionValue[{opt -> 1}, "opt"]OptionValue[{"opt" -> 1}, opt]OptionValue checks that all options requested appear in the defaults:
OptionValue[{a -> 1}, {a, b}]For simple cases, OptionValue[f,opts,name] is similar to name/.opts/.Options[f]:
Options[f] = {a -> x, b -> y}OptionValue[f, {b -> 5}, {a, b}]{a, b} /. {b -> 5} /. Options[f]However, OptionValue performs additional normalization to ensure rules are correctly applied:
OptionValue[f, {a -> 7, b -> a}, {a, b}]{a, b} /. {a -> 7, b -> a} /. Options[f]Possible Issues (1)
Define a transformation rule where OptionsPattern only appears inside a different function:
Options[f] = {a -> 1};
Options[g] = {a -> 2};
f[g[OptionsPattern[]]] := {OptionValue[a], OptionValue[f, a], OptionValue[g, a]}OptionValue[a] does not work because OptionsPattern is not an argument of f:
f[g[]]Tech Notes
Related Guides
Related Workflows
- Define a Function with Options
History
Text
Wolfram Research (2007), OptionValue, Wolfram Language function, https://reference.wolfram.com/language/ref/OptionValue.html.
CMS
Wolfram Language. 2007. "OptionValue." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/OptionValue.html.
APA
Wolfram Language. (2007). OptionValue. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/OptionValue.html
BibTeX
@misc{reference.wolfram_2026_optionvalue, author="Wolfram Research", title="{OptionValue}", year="2007", howpublished="\url{https://reference.wolfram.com/language/ref/OptionValue.html}", note=[Accessed: 13-June-2026]}
BibLaTeX
@online{reference.wolfram_2026_optionvalue, organization={Wolfram Research}, title={OptionValue}, year={2007}, url={https://reference.wolfram.com/language/ref/OptionValue.html}, note=[Accessed: 13-June-2026]}