> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kotlin Top-Level Property
A top-level property in Kotlin is a property declared directly at the root of a `.kt` file, outside the scope of any class, interface, or object declaration. It is scoped to the package in which it is defined and is initialized when the file's corresponding generated class is loaded by the ClassLoader.
## Syntax
Top-level properties are declared using standard `val` (read-only) or `var` (mutable) keywords. They support explicit initialization, type inference, and custom accessors.
```kotlin theme={"dark"}
package com.example.core
// Read-only top-level property
val systemVersion: String = "1.0.0"
// Mutable top-level property
var activeConnections: Int = 0
// Compile-time constant top-level property
const val MAX_RETRIES: Int = 3
// Top-level property with custom accessors (no backing field generated)
var connectionMultiplier: Int
get() = activeConnections * 2
set(value) {
activeConnections = value / 2
}
```
## JVM Compilation Mechanics
Because the Java Virtual Machine (JVM) requires all fields and methods to be encapsulated within a class, the Kotlin compiler generates a facade class to host top-level properties. By default, if the file is named `Network.kt`, the compiler generates a `public final class` named `NetworkKt`.
The compilation behavior depends on the property declaration:
1. **Standard `val` and `var`**:
The compiler generates a `private static` backing field. It then generates a `public static final` getter method (and a setter method for `var`) to control access to that field.
2. **`const val`**:
The compiler generates a `public static final` field. No getter is generated. The value is inlined at the call site during compilation.
3. **Custom Accessors (without `field` reference)**:
The compiler generates `public static final` getter/setter methods but omits the `private static` backing field entirely.
## Visibility Modifiers
Visibility modifiers applied to top-level properties dictate their accessibility across the codebase:
* `public` (default): The property is accessible from anywhere in the project.
* `internal`: The property is accessible from anywhere within the same compiled module.
* `private`: The property is accessible *only* within the specific `.kt` file where it is declared. The generated static field and methods are marked `private` in the bytecode.
* `protected`: Not allowed on top-level declarations.
## Java Interoperability
When accessing Kotlin top-level properties from Java code, developers must invoke the generated static accessors on the file's facade class.
```java theme={"dark"}
// Java code accessing properties from Network.kt
String version = NetworkKt.getSystemVersion();
NetworkKt.setActiveConnections(5);
// const val is accessed directly as a static field
int retries = NetworkKt.MAX_RETRIES;
```
### Modifying Java Interoperability
You can alter how the JVM compiles top-level properties using annotations:
* **`@file:JvmName("CustomName")`**: Placed at the very top of the `.kt` file (before the package declaration), this changes the name of the generated facade class.
* **`@JvmField`**: Instructs the compiler not to generate getters/setters, but instead expose the property as a `public static` field.
```kotlin theme={"dark"}
@file:JvmName("NetworkUtils")
package com.example.core
@JvmField
val defaultTimeout: Int = 5000
```
```java theme={"dark"}
// Java access after applying annotations
int timeout = NetworkUtils.defaultTimeout;
```
Tired of Poor Kotlin Skills? Fix That With Deep Grasping!
Learn More
