<!--
{
  "availability" : [
    "iOS: 7.0.0 -",
    "iPadOS: 7.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.9.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "JavaScriptCore",
  "identifier" : "/documentation/JavaScriptCore/JSValue",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "JavaScriptCore"
    ],
    "preciseIdentifier" : "c:objc(cs)JSValue"
  },
  "title" : "JSValue"
}
-->

# JSValue

A JavaScript value.

```
class JSValue
```

## Overview

You use the [`JSValue`](/documentation/JavaScriptCore/JSValue) class to convert basic values, such as numbers and strings, between JavaScript and Objective-C or Swift representations to pass data between native code and JavaScript code. You can also use this class to create JavaScript objects that wrap native objects of custom classes or JavaScript functions with implementations that native methods or blocks provide.

Each [`JSValue`](/documentation/JavaScriptCore/JSValue) instance originates from a [`JSContext`](/documentation/JavaScriptCore/JSContext) object that represents the JavaScript execution environment containing that value. The value holds a strong reference to its [`context`](/documentation/JavaScriptCore/JSValue/context) object — as long as it retains any value for a particular [`JSContext`](/documentation/JavaScriptCore/JSContext) instance, that context remains alive. When you invoke an instance method on a [`JSValue`](/documentation/JavaScriptCore/JSValue) object, and that method returns another [`JSValue`](/documentation/JavaScriptCore/JSValue) object, the returned value belongs to the same context as the original value.

Each JavaScript value also has an association (indirectly via the [`context`](/documentation/JavaScriptCore/JSValue/context) property) with a specific [`JSVirtualMachine`](/documentation/JavaScriptCore/JSVirtualMachine) object that represents the underlying set of execution resources for its context. You can pass [`JSValue`](/documentation/JavaScriptCore/JSValue) instances only to methods on [`JSValue`](/documentation/JavaScriptCore/JSValue) and [`JSContext`](/documentation/JavaScriptCore/JSContext) instances on the same virtual machine — attempting to pass a value to a different virtual machine raises an Objective-C exception.

### Convert Between JavaScript and Native Types

When you use the [`JSValue`](/documentation/JavaScriptCore/JSValue) methods for creating, reading, and converting JavaScript values, JavaScriptCore automatically converts native values to JavaScript values and vice versa, using the rules below.

- <doc://com.apple.documentation/documentation/Foundation/NSDictionary> objects or Swift dictionaries and the keys they contain become JavaScript objects with matching named properties and vice versa. JavaScriptCore recursively copies and converts the values for keys.
- <doc://com.apple.documentation/documentation/Foundation/NSArray> objects or Swift arrays become JavaScript arrays and vice versa, with elements that JavaScriptCore recursively copies and converts.
- Objective-C blocks (or Swift closures with the `@convention(block)` attribute) become JavaScript `Function` objects, with parameter and return types that JavaScriptCore converts using the same rules as values. Converting a JavaScript function with a backing from a native block or method returns that block or method; all other JavaScript functions convert as empty dictionaries.
- For all other native object types (and class types or metatypes), JavaScriptCore creates a JavaScript wrapper object with a constructor prototype chain that reflects the native class hierarchy. By default, the JavaScript wrapper for a native object doesn’t make that object’s properties and methods available in JavaScript. To choose properties and methods for export to JavaScript, see [`JSExport`](/documentation/JavaScriptCore/JSExport).

When you convert an object, method, or block, JavaScriptCore implicitly converts the types and values of object properties and method parameters using the rules below:

|Objective-C (and Swift) types                                                                                                                                                                                                                                                                                                              |JavaScript types   |Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`nil`                                                                                                                                                                                                                                                                                                                                      |`undefined`        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|<doc://com.apple.documentation/documentation/Foundation/NSNull>                                                                                                                                                                                                                                                                            |`null`             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|<doc://com.apple.documentation/documentation/Foundation/NSString> (Swift <doc://com.apple.documentation/documentation/Swift/String>)                                                                                                                                                                                                       |`String`           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|<doc://com.apple.documentation/documentation/Foundation/NSNumber> and primitive numeric types                                                                                                                                                                                                                                              |`Number`, `Boolean`|Conversion is consistent with the following methods: ![](spacer) ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(int32:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toInt32()`` for signed integer types ![](spacer) ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(uInt32:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toUInt32()`` for unsigned integer types ![](spacer) ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(bool:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toBool()`` for Boolean types ![](spacer) ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(double:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toBool()`` for all other numeric types|
|<doc://com.apple.documentation/documentation/Foundation/NSDictionary> (Swift <doc://com.apple.documentation/documentation/Swift/Dictionary>)                                                                                                                                                                                               |`Object`           |Recursive conversion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|<doc://com.apple.documentation/documentation/Foundation/NSArray> (Swift <doc://com.apple.documentation/documentation/Swift/Array>)                                                                                                                                                                                                         |`Array`            |Recursive conversion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|<doc://com.apple.documentation/documentation/Foundation/NSDate>                                                                                                                                                                                                                                                                            |`Date`             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|Objective-C or Swift object (<doc://com.apple.documentation/documentation/ObjectiveC/objc_object> or <doc://com.apple.documentation/documentation/Swift/AnyObject>) ![](spacer) Objective-C or Swift class (<doc://com.apple.documentation/documentation/ObjectiveC/Class> or <doc://com.apple.documentation/documentation/Swift/AnyClass>)|`Object`           |Converts with ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(object:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toObject()``.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|Structure types: ![](spacer) <doc://com.apple.documentation/documentation/Foundation/NSRange-c.struct>, <doc://com.apple.documentation/documentation/CoreFoundation/CGRect>, <doc://com.apple.documentation/documentation/CoreFoundation/CGPoint>, <doc://com.apple.documentation/documentation/CoreFoundation/CGSize>                     |`Object`           |There isn’t support for other structure types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|Objective-C block (Swift closure)                                                                                                                                                                                                                                                                                                          |`Function`         |Convert explicitly with ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/init(object:in:)`` / ``doc://com.apple.javascriptcore/documentation/JavaScriptCore/JSValue/toObject()``. ![](spacer) JavaScript functions don’t convert to native blocks/closures unless they already have a backing from a native block/closure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## Topics

### Creating JavaScript Values

[`init(object:in:)`](/documentation/JavaScriptCore/JSValue/init(object:in:))

Creates a JavaScript value by converting the specified native object.

[`init(bool:in:)`](/documentation/JavaScriptCore/JSValue/init(bool:in:))

Creates a JavaScript representation of the specified Boolean value.

[`init(double:in:)`](/documentation/JavaScriptCore/JSValue/init(double:in:))

Creates a JavaScript representation of the specified floating-point value.

[`init(int32:in:)`](/documentation/JavaScriptCore/JSValue/init(int32:in:))

Creates a JavaScript representation of the specified signed integer value.

[`init(uInt32:in:)`](/documentation/JavaScriptCore/JSValue/init(uInt32:in:))

Creates a JavaScript representation of the specified unsigned integer value.

[`init(newObjectIn:)`](/documentation/JavaScriptCore/JSValue/init(newObjectIn:))

Creates a new, empty JavaScript object value.

[`init(newArrayIn:)`](/documentation/JavaScriptCore/JSValue/init(newArrayIn:))

Creates a new, empty JavaScript array value.

[`init(newRegularExpressionFromPattern:flags:in:)`](/documentation/JavaScriptCore/JSValue/init(newRegularExpressionFromPattern:flags:in:))

Creates a JavaScript regular expression value from the specified pattern.

[`init(newErrorFromMessage:in:)`](/documentation/JavaScriptCore/JSValue/init(newErrorFromMessage:in:))

Creates a JavaScript error value with the specified error message.

[`init(undefinedIn:)`](/documentation/JavaScriptCore/JSValue/init(undefinedIn:))

Creates a JavaScript `undefined` value.

[`init(nullIn:)`](/documentation/JavaScriptCore/JSValue/init(nullIn:))

Creates a JavaScript `null` value.

[`init(point:inContext:)`](/documentation/JavaScriptCore/JSValue/init(point:inContext:))

Creates a JavaScript representation of the specified point.

[`init(range:inContext:)`](/documentation/JavaScriptCore/JSValue/init(range:inContext:))

Creates a JavaScript representation of the specified range.

[`init(rect:inContext:)`](/documentation/JavaScriptCore/JSValue/init(rect:inContext:))

Creates a JavaScript representation of the specified rectangle.

[`init(size:inContext:)`](/documentation/JavaScriptCore/JSValue/init(size:inContext:))

Creates a JavaScript representation of the specified width and height.

[`init(newSymbolFromDescription:in:)`](/documentation/JavaScriptCore/JSValue/init(newSymbolFromDescription:in:))

Creates a unique symbol object.

[`init(newPromiseIn:fromExecutor:)`](/documentation/JavaScriptCore/JSValue/init(newPromiseIn:fromExecutor:))

Creates a promise object using the specified executor callback.

[`init(newPromiseRejectedWithReason:in:)`](/documentation/JavaScriptCore/JSValue/init(newPromiseRejectedWithReason:in:))

Creates a rejected promise object with the specified value.

[`init(newPromiseResolvedWithResult:in:)`](/documentation/JavaScriptCore/JSValue/init(newPromiseResolvedWithResult:in:))

Creates a resolved promise object with the specified value.

### Reading and Converting JavaScript Values

[`toObject()`](/documentation/JavaScriptCore/JSValue/toObject())

Converts the JavaScript value to a native object.

[`toObjectOf(_:)`](/documentation/JavaScriptCore/JSValue/toObjectOf(_:))

Converts the JavaScript value to a native object of the specified class.

[`toBool()`](/documentation/JavaScriptCore/JSValue/toBool())

Converts the JavaScript value to a native Boolean value.

[`toDouble()`](/documentation/JavaScriptCore/JSValue/toDouble())

Converts the JavaScript value to a native floating-point value.

[`toInt32()`](/documentation/JavaScriptCore/JSValue/toInt32())

Converts the JavaScript value to a native signed integer value.

[`toUInt32()`](/documentation/JavaScriptCore/JSValue/toUInt32())

Converts the JavaScript value to a native unsigned integer value.

[`toNumber()`](/documentation/JavaScriptCore/JSValue/toNumber())

Converts the JavaScript value to a <doc://com.apple.documentation/documentation/Foundation/NSNumber> object.

[`toString()`](/documentation/JavaScriptCore/JSValue/toString())

Converts the JavaScript value to a native string.

[`toDate()`](/documentation/JavaScriptCore/JSValue/toDate())

Converts the JavaScript value to a date object.

[`toArray()`](/documentation/JavaScriptCore/JSValue/toArray())

Converts the JavaScript value to an array.

[`toDictionary()`](/documentation/JavaScriptCore/JSValue/toDictionary())

Converts the JavaScript value to a dictionary.

[`toPoint()`](/documentation/JavaScriptCore/JSValue/toPoint())

Converts the value to a point structure.

[`toRange()`](/documentation/JavaScriptCore/JSValue/toRange())

Converts the value to a range.

[`toRect()`](/documentation/JavaScriptCore/JSValue/toRect())

Converts the value to a rectangle structure.

[`toSize()`](/documentation/JavaScriptCore/JSValue/toSize())

Converts the value to a size.

### Determining the Type of a JavaScript Value

[`isUndefined`](/documentation/JavaScriptCore/JSValue/isUndefined)

A Boolean value that indicates whether the instance corresponds to the JavaScript `undefined` value.

[`isNull`](/documentation/JavaScriptCore/JSValue/isNull)

A Boolean value that indicates whether the instance corresponds to the JavaScript `null` value.

[`isBoolean`](/documentation/JavaScriptCore/JSValue/isBoolean)

A Boolean value that indicates whether the instance is a JavaScript Boolean value.

[`isNumber`](/documentation/JavaScriptCore/JSValue/isNumber)

A Boolean value that indicates whether the instance is a JavaScript numeric value.

[`isString`](/documentation/JavaScriptCore/JSValue/isString)

A Boolean value that indicates whether the instance is a JavaScript `String` object.

[`isObject`](/documentation/JavaScriptCore/JSValue/isObject)

A Boolean value that indicates whether the instance is a JavaScript object.

[`isArray`](/documentation/JavaScriptCore/JSValue/isArray)

A Boolean value that indicates whether the instance is a JavaScript array value.

[`isDate`](/documentation/JavaScriptCore/JSValue/isDate)

A Boolean value that indicates whether the instance is a JavaScript `Date` object.

[`isSymbol`](/documentation/JavaScriptCore/JSValue/isSymbol)

A Boolean value that indicates whether the instance is a symbol.

### Comparing JavaScript Values

[`isEqual(to:)`](/documentation/JavaScriptCore/JSValue/isEqual(to:))

Compares the value to another for strict equality.

[`isEqualWithTypeCoercion(to:)`](/documentation/JavaScriptCore/JSValue/isEqualWithTypeCoercion(to:))

Compares the value to another for equivalence, allowing type conversion.

[`isInstance(of:)`](/documentation/JavaScriptCore/JSValue/isInstance(of:))

Returns a Boolean value indicating whether the value is an instance of another JavaScript object value.

### Working with Function and Constructor Values

[`call(withArguments:)`](/documentation/JavaScriptCore/JSValue/call(withArguments:))

Invokes the value as a JavaScript function.

[`construct(withArguments:)`](/documentation/JavaScriptCore/JSValue/construct(withArguments:))

Invokes the value as a JavaScript constructor.

[`invokeMethod(_:withArguments:)`](/documentation/JavaScriptCore/JSValue/invokeMethod(_:withArguments:))

Calls the named JavaScript method on the value.

### Working with Container Values

[`defineProperty(_:descriptor:)`](/documentation/JavaScriptCore/JSValue/defineProperty(_:descriptor:))

Defines a property on the JavaScript object value or modifies a property’s definition.

[`hasProperty(_:)`](/documentation/JavaScriptCore/JSValue/hasProperty(_:))

Returns a Boolean value indicating whether the JavaScript value has a defined property with the specified name.

[`deleteProperty(_:)`](/documentation/JavaScriptCore/JSValue/deleteProperty(_:))

Deletes the named property from the JavaScript object value.

[`atIndex(_:)`](/documentation/JavaScriptCore/JSValue/atIndex(_:))

Returns the value at the specified numeric index in the JavaScript object value.

[`setValue(_:at:)`](/documentation/JavaScriptCore/JSValue/setValue(_:at:))

Sets the value at the specified numeric index in the JavaScript object value.

[`forProperty(_:)`](/documentation/JavaScriptCore/JSValue/forProperty(_:))

Returns the value of the named property in the JavaScript object value.

[`setValue(_:forProperty:)`](/documentation/JavaScriptCore/JSValue/setValue(_:forProperty:))

Sets the value of the named property in the JavaScript object value.

[`JSValueProperty`](/documentation/JavaScriptCore/JSValueProperty)

A type that identifies a property of a JavaScript value.

### Accessing a Value’s JavaScript Context

[`context`](/documentation/JavaScriptCore/JSValue/context)

The JavaScript context hosting this value.

### Accessing Values with Subscript Syntax

[`objectAtIndexedSubscript(_:)`](/documentation/JavaScriptCore/JSValue/objectAtIndexedSubscript(_:))

Returns the value’s JavaScript property at the specified index, allowing subscript syntax.

[`setObject(_:atIndexedSubscript:)`](/documentation/JavaScriptCore/JSValue/setObject(_:atIndexedSubscript:))

Sets the value’s JavaScript property at the specified index, allowing subscript syntax.

[`objectForKeyedSubscript(_:)`](/documentation/JavaScriptCore/JSValue/objectForKeyedSubscript(_:))

Returns the value’s JavaScript property named with the specified key, allowing subscript syntax.

[`setObject(_:forKeyedSubscript:)`](/documentation/JavaScriptCore/JSValue/setObject(_:forKeyedSubscript:))

Sets the value’s JavaScript property named with the specified key, allowing subscript syntax.

### Working with the C JavaScriptCore API

[`jsValueRef`](/documentation/JavaScriptCore/JSValue/jsValueRef)

Returns the C representation of the JavaScript value.

[`init(JSValueRef:inContext:)`](/documentation/JavaScriptCore/JSValue/init(JSValueRef:inContext:))

Creates a JavaScript value object from the equivalent C representation.

### Constants

[Property Descriptor Keys](/documentation/JavaScriptCore/property-descriptor-keys)

Keys for the native dictionary representation of a JavaScript property descriptor, used with the [`defineProperty(_:descriptor:)`](/documentation/JavaScriptCore/JSValue/defineProperty(_:descriptor:)) method.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)